API Docs

Create a new Rune order

post

https://api.ordinalsbot.com/tokenpayhttps://signet-api.ordinalsbot.com/tokenpayhttps://testnet-api.ordinalsbot.com/tokenpay

/user/order/rune

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

application/json

amountnumberOptional

The amount for the order.

Example: 1

tokenstringOptional

The token for the order.

Example: SHITCOINPARADISE

webhookUrlstringOptional

The webhook URL for the order.

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

additionalFeeintegerOptional

The additional fee for the order.

Example: 0

descriptionstringOptional

The description for the order.

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

Responses

200

Successfully created the order.

application/json

idstringOptionalExample: b15ad7f6-b34a-4a1e-8c0f-30492610a3d6

createdAtintegerOptionalExample: 1730120609939

accountIdstringOptionalExample: ordinalsbot

webhookUrlstringOptionalExample: https://api.ordinalsbot.com/webhook/tokenpay

successUrlstringOptional

statestringOptionalExample: pending

descriptionstringOptionalExample: 56f3f01e-407b-4099-b172-591501f7129d

webhookSecretTokenstringOptional

Sent only when webhookUrl is provided. 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.

Example: c051a42521ab8d2987c3626a6246d99f8a3397cd6be626ee0eeb7f5457e92432

400

Bad request. Invalid input parameters.

application/json

500

Internal server error.

application/json

post

/user/order/rune

HTTPcURLJavaScriptPython

POST /tokenpay/user/order/rune HTTP/1.1
Host: api.ordinalsbot.com
x-api-key: your-api-key
Content-Type: application/json
Accept: */*
Content-Length: 183

{
  "amount": 1,
  "token": "SHITCOINPARADISE",
  "webhookUrl": "https://webhook.site/f5a2dcec-b7e4-4845-92d1-22ded0057104",
  "additionalFee": 0,
  "description": "e14fefbe-fc23-40a2-b0d6-6aab7bff3438"
}

{
  "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"
}

Check specific transaction by txid

post

https://api.ordinalsbot.com/tokenpayhttps://signet-api.ordinalsbot.com/tokenpayhttps://testnet-api.ordinalsbot.com/tokenpay

/utils/checktx

Body

application/json

txidstringOptional

The transaction ID to be validated.

Example: 1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef

Responses

200

A successful response

application/json

txidstringOptionalExample: f358178f7f72a07cb983da3b19097a5b8a8160b367609701d3d1c15e7f3147e4

post

/utils/checktx

HTTPcURLJavaScriptPython

POST /tokenpay/utils/checktx HTTP/1.1
Host: api.ordinalsbot.com
Content-Type: application/json
Accept: */*
Content-Length: 75

{
  "txid": "1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef"
}

200

A successful response

{
  "txid": "f358178f7f72a07cb983da3b19097a5b8a8160b367609701d3d1c15e7f3147e4"
}

Retrieve an order by ID

get

https://api.ordinalsbot.com/tokenpayhttps://signet-api.ordinalsbot.com/tokenpayhttps://testnet-api.ordinalsbot.com/tokenpay

/order/{orderId}

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

200

Successfully retrieved the order.

application/json

createdAtintegerOptionalExample: 1721745751531

accountIdstringOptionalExample: ordinalsbot

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

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

statestringOptionalExample: pending

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

404

Order not found.

application/json

get

/order/{orderId}

HTTPcURLJavaScriptPython

GET /tokenpay/order/{orderId} HTTP/1.1
Host: api.ordinalsbot.com
Accept: */*

{
  "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"
}

Withdraw funds from user account

post

https://api.ordinalsbot.com/tokenpayhttps://signet-api.ordinalsbot.com/tokenpayhttps://testnet-api.ordinalsbot.com/tokenpay

/user/account/withdraw

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

application/json

protocolstringOptional

The protocol for the withdrawal.

Example: bitcoin

tokenstringOptional

The token for the withdrawal.

Example: BTC

amountnumberOptional

The amount to withdraw.

Example: 0.5

addressstringOptional

The address to withdraw to.

Example: bc1qh3rp2pns6nrr8mhx0rlzd5kktwm33wc4ax0h4y

Responses

200

Successfully created the withdrawal request.

application/json

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

accountIdstringOptionalExample: user123

protocolstringOptionalExample: bitcoin

tokenstringOptionalExample: BTC

amountnumberOptionalExample: 0.5

addressstringOptionalExample: bc1qh3rp2pns6nrr8mhx0rlzd5kktwm33wc4ax0h4y

statestringOptionalExample: pending

createdAtintegerOptionalExample: 1721745751531

400

Bad request. Invalid input parameters.

application/json

500

Internal server error.

application/json

post

/user/account/withdraw

HTTPcURLJavaScriptPython

POST /tokenpay/user/account/withdraw HTTP/1.1
Host: api.ordinalsbot.com
x-api-key: your-api-key
Content-Type: application/json
Accept: */*
Content-Length: 104

{
  "protocol": "bitcoin",
  "token": "BTC",
  "amount": 0.5,
  "address": "bc1qh3rp2pns6nrr8mhx0rlzd5kktwm33wc4ax0h4y"
}

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

Get withdrawal details

get

https://api.ordinalsbot.com/tokenpayhttps://signet-api.ordinalsbot.com/tokenpayhttps://testnet-api.ordinalsbot.com/tokenpay

/user/withdrawal/{withdrawalId}

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

200

Successfully retrieved the withdrawal details.

application/json

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

accountIdstringOptionalExample: user123

protocolstringOptionalExample: bitcoin

tokenstringOptionalExample: BTC

amountnumberOptionalExample: 0.5

addressstringOptionalExample: bc1qh3rp2pns6nrr8mhx0rlzd5kktwm33wc4ax0h4y

statestringOptionalExample: completed

createdAtintegerOptionalExample: 1721745751531

400

Bad request. Invalid input parameters.

application/json

404

Withdrawal not found.

application/json

500

Internal server error.

application/json

get

/user/withdrawal/{withdrawalId}

HTTPcURLJavaScriptPython

GET /tokenpay/user/withdrawal/{withdrawalId} HTTP/1.1
Host: api.ordinalsbot.com
x-api-key: your-api-key
Accept: */*

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

Create a payment PSBT

post

https://api.ordinalsbot.com/tokenpayhttps://signet-api.ordinalsbot.com/tokenpayhttps://testnet-api.ordinalsbot.com/tokenpay

/create-payment-psbt

Handles the creation of a payment PSBT.

Body

application/json

orderIdstringOptional

The ID of the order.

Example: order123

paymentAddressstringOptional

The payment address.

Example: 1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa

paymentPublicKeystringOptional

The payment public key.

Example: 02b463a1e6b8e1a1e1a1e1a1e1a1e1a1e1a1e1a1e1a1e1a1e1a1e1a1e1a1e1a1

ordinalAddressstringOptional

The ordinal address.

Example: bc1qw508d6qejxtdg4y5r3zarvary0c5xw7kygt080

ordinalPublicKeystringOptional

The ordinal public key.

Example: 03b463a1e6b8e1a1e1a1e1a1e1a1e1a1e1a1e1a1e1a1e1a1e1a1e1a1e1a1e1a1

feeRatenumberOptional

The fee rate for the transaction.

Example: 0.0001

Responses

200

Successfully created the payment PSBT.

application/json

psbtstringOptional

The created PSBT.

Example: cHNidP8BAFICAAAA...

400

Bad request. Invalid input parameters.

application/json

500

Internal server error.

application/json

post

/create-payment-psbt

HTTPcURLJavaScriptPython

POST /tokenpay/create-payment-psbt HTTP/1.1
Host: api.ordinalsbot.com
Content-Type: application/json
Accept: */*
Content-Length: 327

{
  "orderId": "order123",
  "paymentAddress": "1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa",
  "paymentPublicKey": "02b463a1e6b8e1a1e1a1e1a1e1a1e1a1e1a1e1a1e1a1e1a1e1a1e1a1e1a1e1a1",
  "ordinalAddress": "bc1qw508d6qejxtdg4y5r3zarvary0c5xw7kygt080",
  "ordinalPublicKey": "03b463a1e6b8e1a1e1a1e1a1e1a1e1a1e1a1e1a1e1a1e1a1e1a1e1a1e1a1e1a1",
  "feeRate": 0.0001
}

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

Get account balance

get

https://api.ordinalsbot.com/tokenpayhttps://signet-api.ordinalsbot.com/tokenpayhttps://testnet-api.ordinalsbot.com/tokenpay

/user/account/balance

Retrieves the balance of a specific user account.

Header parameters

x-api-keystringRequired

API key for authentication.

Example: your-api-key

Responses

200

Successfully retrieved the account balance.

application/json

400

Bad request. Invalid input parameters.

application/json

404

Account not found.

application/json

500

Internal server error.

application/json

get

/user/account/balance

HTTPcURLJavaScriptPython

GET /tokenpay/user/account/balance HTTP/1.1
Host: api.ordinalsbot.com
x-api-key: your-api-key
Accept: */*

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