API Docs

PreviousWhat is TokenPay?NextAPI reference

Last updated 7 months ago

Create a new Rune order

post

Creates a new Rune order with the specified details. If webhookUrl is provided, a webhookSecretToken will be sent in the response. webhookSecretToken is a shared secret between the server and the user. It is the only way to authenticate the incoming webhooks. It is unique for every order. webhookSecretToken should be saved by the user in the database and checked on every received webhook.

Header parameters

x-api-keystringrequired

API key for authentication.

Example: your-api-key

Body

amountnumber

The amount for the order.

Example: 1

tokenstring

The token for the order.

Example: SHITCOINPARADISE

webhookUrlstring

The webhook URL for the order.

Example: https://webhook.site/f5a2dcec-b7e4-4845-92d1-22ded0057104

additionalFeeinteger

The additional fee for the order.

Example: 0

descriptionstring

The description for the order.

Example: e14fefbe-fc23-40a2-b0d6-6aab7bff3438

Responses

application/json

cURL

JavaScript

Python

HTTP

curl -L \
  --request POST \
  --url 'https://api.ordinalsbot.com/tokenpay/user/order/rune' \
  --header 'x-api-key: your-api-key' \
  --header 'Content-Type: application/json' \
  --data '{
    "amount": 1,
    "token": "SHITCOINPARADISE",
    "webhookUrl": "https://webhook.site/f5a2dcec-b7e4-4845-92d1-22ded0057104",
    "additionalFee": 0,
    "description": "e14fefbe-fc23-40a2-b0d6-6aab7bff3438"
  }'

200

400

500

{
  "id": "b15ad7f6-b34a-4a1e-8c0f-30492610a3d6",
  "createdAt": 1730120609939,
  "accountId": "ordinalsbot",
  "feeCharge": {
    "amount": 100,
    "token": "BTC",
    "address": "bc1qd0a0kq9hdmem24x229s7pytgp759et7takws72",
    "state": "pending_payment",
    "protocol": "bitcoin",
    "txid": null,
    "createdAt": 1730120609719,
    "additionalFee": 100
  },
  "tokenCharge": {
    "amount": 1,
    "token": "SHITCOIN•PARADISE",
    "address": "bc1prhdced0h23ppfvqqk2pe5k092u5ncev8rmvvlz6h5kvezcd2g93qfjmg9v",
    "state": "pending_payment",
    "protocol": "rune",
    "txid": null,
    "createdAt": 1730120609939,
    "additionalFee": 0
  },
  "webhookUrl": "https://api.ordinalsbot.com/webhook/tokenpay",
  "successUrl": null,
  "state": "pending",
  "description": "56f3f01e-407b-4099-b172-591501f7129d",
  "webhookSecretToken": "c051a42521ab8d2987c3626a6246d99f8a3397cd6be626ee0eeb7f5457e92432"
}

Successfully created the order.

Check specific transaction by txid

post

Body

txidstring

The transaction ID to be validated.

Example: 1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef

Responses

application/json

cURL

JavaScript

Python

HTTP

curl -L \
  --request POST \
  --url 'https://api.ordinalsbot.com/tokenpay/utils/checktx' \
  --header 'Content-Type: application/json' \
  --data '{
    "txid": "1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef"
  }'

200

{
  "txid": "f358178f7f72a07cb983da3b19097a5b8a8160b367609701d3d1c15e7f3147e4"
}

A successful response

Retrieve an order by ID

get

Fetches an order from the Firestore database using the provided order ID.

Path parameters

orderIdstringrequired

The ID of the order to retrieve.

Example: 1234567890abcdef

Responses

application/json

cURL

JavaScript

Python

HTTP

curl -L \
  --url 'https://api.ordinalsbot.com/tokenpay/order/{orderId}'

200

404

{
  "createdAt": 1721745751531,
  "accountId": "ordinalsbot",
  "feeCharge": {
    "createdAt": 1721745751432,
    "additionalFee": 23315,
    "amount": 32315,
    "protocol": "bitcoin",
    "address": "bc1qh3rp2pns6nrr8mhx0rlzd5kktwm33wc4ax0h4y",
    "txid": null,
    "state": "pending_payment",
    "token": "BTC"
  },
  "description": "e14fefbe-fc23-40a2-b0d6-6aab7bff3438",
  "id": "f2bcddd4-bd8d-4c88-bf8a-61be0d5b0600",
  "state": "pending",
  "tokenCharge": {
    "createdAt": 1721745751530,
    "additionalFee": 0,
    "amount": 1,
    "protocol": "rune",
    "address": "bc1p76ppg0q24p2v6faxkaffrvtg0n9u2wvgjzr2g48nfnhk6z7g8wasnwtsql",
    "txid": null,
    "state": "pending_payment",
    "token": "SHITCOINPARADISE"
  },
  "webhookUrl": "https://webhook.site/f5a2dcec-b7e4-4845-92d1-22ded0057104"
}

Successfully retrieved the order.

Withdraw funds from user account

post

Withdraws funds from the user's account to the specified address.

Header parameters

x-api-keystringrequired

API key for authentication.

Example: your-api-key

Body

protocolstring

The protocol for the withdrawal.

Example: bitcoin

tokenstring

The token for the withdrawal.

Example: BTC

amountnumber

The amount to withdraw.

Example: 0.5

addressstring

The address to withdraw to.

Example: bc1qh3rp2pns6nrr8mhx0rlzd5kktwm33wc4ax0h4y

Responses

application/json

cURL

JavaScript

Python

HTTP

curl -L \
  --request POST \
  --url 'https://api.ordinalsbot.com/tokenpay/user/account/withdraw' \
  --header 'x-api-key: your-api-key' \
  --header 'Content-Type: application/json' \
  --data '{
    "protocol": "bitcoin",
    "token": "BTC",
    "amount": 0.5,
    "address": "bc1qh3rp2pns6nrr8mhx0rlzd5kktwm33wc4ax0h4y"
  }'

200

400

500

{
  "id": "f2bcddd4-bd8d-4c88-bf8a-61be0d5b0600",
  "accountId": "user123",
  "protocol": "bitcoin",
  "token": "BTC",
  "amount": 0.5,
  "address": "bc1qh3rp2pns6nrr8mhx0rlzd5kktwm33wc4ax0h4y",
  "state": "pending",
  "createdAt": 1721745751531
}

Successfully created the withdrawal request.

Get withdrawal details

get

Retrieves the details of a specific withdrawal using the withdrawal ID.

Path parameters

withdrawalIdstringrequired

The ID of the withdrawal to retrieve.

Example: f2bcddd4-bd8d-4c88-bf8a-61be0d5b0600

Header parameters

x-api-keystringrequired

API key for authentication.

Example: your-api-key

Responses

application/json

cURL

JavaScript

Python

HTTP

curl -L \
  --url 'https://api.ordinalsbot.com/tokenpay/user/withdrawal/{withdrawalId}' \
  --header 'x-api-key: your-api-key'

200

400

404

500

{
  "id": "f2bcddd4-bd8d-4c88-bf8a-61be0d5b0600",
  "accountId": "user123",
  "protocol": "bitcoin",
  "token": "BTC",
  "amount": 0.5,
  "address": "bc1qh3rp2pns6nrr8mhx0rlzd5kktwm33wc4ax0h4y",
  "state": "completed",
  "createdAt": 1721745751531
}

Successfully retrieved the withdrawal details.

Create a payment PSBT

post

Handles the creation of a payment PSBT.

Body

orderIdstring

The ID of the order.

Example: order123

paymentAddressstring

The payment address.

Example: 1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa

paymentPublicKeystring

The payment public key.

Example: 02b463a1e6b8e1a1e1a1e1a1e1a1e1a1e1a1e1a1e1a1e1a1e1a1e1a1e1a1e1a1

ordinalAddressstring

The ordinal address.

Example: bc1qw508d6qejxtdg4y5r3zarvary0c5xw7kygt080

ordinalPublicKeystring

The ordinal public key.

Example: 03b463a1e6b8e1a1e1a1e1a1e1a1e1a1e1a1e1a1e1a1e1a1e1a1e1a1e1a1e1a1

feeRatenumber

The fee rate for the transaction.

Example: 0.0001

Responses

application/json

cURL

JavaScript

Python

HTTP

curl -L \
  --request POST \
  --url 'https://api.ordinalsbot.com/tokenpay/create-payment-psbt' \
  --header 'Content-Type: application/json' \
  --data '{
    "orderId": "order123",
    "paymentAddress": "1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa",
    "paymentPublicKey": "02b463a1e6b8e1a1e1a1e1a1e1a1e1a1e1a1e1a1e1a1e1a1e1a1e1a1e1a1e1a1",
    "ordinalAddress": "bc1qw508d6qejxtdg4y5r3zarvary0c5xw7kygt080",
    "ordinalPublicKey": "03b463a1e6b8e1a1e1a1e1a1e1a1e1a1e1a1e1a1e1a1e1a1e1a1e1a1e1a1e1a1",
    "feeRate": 0.0001
  }'

200

400

500

{
  "psbt": "cHNidP8BAFICAAAA..."
}

Successfully created the payment PSBT.

Get account balance

get

Retrieves the balance of a specific user account.

Header parameters

x-api-keystringrequired

API key for authentication.

Example: your-api-key

Responses

application/json

cURL

JavaScript

Python

HTTP

curl -L \
  --url 'https://api.ordinalsbot.com/tokenpay/user/account/balance' \
  --header 'x-api-key: your-api-key'

200

400

404

500

{
  "bitcoin": {
    "BTC": 0
  },
  "rune": {
    "XRUNE": 10
  }
}

Successfully retrieved the account balance.