LogoLogo
Back to AppHelp Center
  • Getting Started
    • Welcome
  • OrdinalsBot API
    • Overview
    • Libraries
    • Template-App
    • Signet
    • Testnet
    • Fractal
    • Getting Prices
      • Getting Prices (Legacy)
    • Create a Direct Inscription Order
    • Create a Managed Inscription Order
    • Get Order Status
    • Create a Collection
    • Create a Collection Order
    • Create Text Inscription Order
    • Search Inscriptions
    • Check Rare Sats Inventory
    • Referral Scheme
    • Transaction Accelerator
    • Burning Assets
    • Webhooks
    • Order States
    • Order Types
  • Runes
    • Etch
    • Mint
    • Launchpad
      • Create
      • Mint
      • Get Launchpad
    • Airdrop
  • Token Pay
    • What is TokenPay?
    • API Docs
      • API reference
        • Order
        • Create payment psbt
        • Create burn rune psbt
        • Validate burn rune tx
        • Create burn inscription psbt
        • Utils
          • Checktx
          • Submittx
          • Finalize psbt
        • User
          • Withdrawal
          • Order
            • Rune
          • Account
            • Withdraw
            • Balance
      • Specification
  • Marketplace
    • User Guide: Pre-Inscribed Launchpad API
    • API Docs
    • Editions Launchpad
  • Launchpad API
    • Create Marketplace
    • Create a new Launchpad
    • Retrieve Launch PSBT
    • Confirm Launch
    • Check Allocation
    • Check for Padding Outputs
    • Setup Padding Outputs
    • Create buy offer
    • Confirm buy offer
    • Get Launch Info
  • Sat Scanner API
    • Find Special Ranges
    • Find Special Ranges UTXO
    • Supported Satributes
  • Sat Extractor
    • Extract
  • BRC20 API
    • OPI API
  • SNS API
    • SNS API
  • Mempool API
    • Mempool API
  • TAP PROTOCOL
    • Tap Reader API
  • UTXO
    • Split
  • User Guide
    • Inscribe your first Ordinal
    • Receiving Payments
  • Knowledge Base
    • Ordinals
      • What is an Ordinal?
      • Satoshi Rarity
      • What are BRC-20 Tokens?
      • Image Optimisation
      • Pixel Art
    • Bitcoin
      • Unspent Transaction Output (UTXO)
  • Official Links
    • Twitter
    • Discord
Powered by GitBook
On this page
  1. Token Pay

API Docs

PreviousWhat is TokenPay?NextAPI reference

Last updated 9 months ago

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
200
Successfully retrieved the order.
application/json
404
Order not found.
application/json
get
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"
}

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
200
Successfully retrieved the withdrawal details.
application/json
400
Bad request. Invalid input parameters.
application/json
404
Withdrawal not found.
application/json
500
Internal server error.
application/json
get
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
}

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
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
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
  }
}
  • POSTCreate a new Rune order
  • POSTCheck specific transaction by txid
  • GETRetrieve an order by ID
  • POSTWithdraw funds from user account
  • GETGet withdrawal details
  • POSTCreate a payment PSBT
  • GETGet account balance

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
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
400
Bad request. Invalid input parameters.
application/json
500
Internal server error.
application/json
post
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
Body
txidstringOptional

The transaction ID to be validated.

Example: 1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef
Responses
200
A successful response
application/json
post
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"
}

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
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
400
Bad request. Invalid input parameters.
application/json
500
Internal server error.
application/json
post
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
}

Create a payment PSBT

post

Handles the creation of a payment PSBT.

Body
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
400
Bad request. Invalid input parameters.
application/json
500
Internal server error.
application/json
post
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..."
}