{"openapi":"3.0.0","info":{"title":"TokenPay","version":"0.1.1"},"servers":[{"url":"https://api.ordinalsbot.com/tokenpay","description":"Production"},{"url":"https://signet-api.ordinalsbot.com/tokenpay","description":"Signet"},{"url":"https://testnet-api.ordinalsbot.com/tokenpay","description":"Testnet"}],"paths":{"/utils/checktx":{"post":{"tags":["Utils"],"summary":"Check specific transaction by txid","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"txid":{"type":"string","description":"The transaction ID to be validated.","example":"1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef"}}}}}},"responses":{"200":{"description":"A successful response","content":{"application/json":{"schema":{"type":"object","properties":{"txid":{"type":"string","example":"f358178f7f72a07cb983da3b19097a5b8a8160b367609701d3d1c15e7f3147e4"}}}}}}}}},"/utils/submittx":{"post":{"tags":["Utils"],"summary":"submit signed raw transaction hex to bitcoin network","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"hex":{"type":"string","description":"The transaction hex","example":"02000000000102278718f8db50b78d8fd466e1c6a41155d36cb42563d51582b4eb26c8b550..."}}}}}},"responses":{"200":{"description":"A successful response","content":{"application/json":{"schema":{"type":"object","properties":{"txid":{"type":"string","example":"f358178f7f72a07cb983da3b19097a5b8a8160b367609701d3d1c15e7f3147e4"}}}}}}}}},"/utils/finalize-psbt":{"post":{"tags":["Utils"],"summary":"finalize a signed PSBT to get a signed transaction hex","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"psbt":{"type":"string","description":"The signed base64 encoded PSBT string","example":"cHNidP8BAKYCAAAAAieHGPjbULeNj9Rm4cakEVXTbLQlY9UVgrTrJsi1UOq8JQAAAAD/////hhF/BOfQgy3mLPXkUKIfa3VTNhOtYPClJSUp+JcKqkoCAAAAAP////8DIgIAAAAAAAABaugDAAAAAAAAF6kUf/+VokrDV6..."}}}}}},"responses":{"200":{"description":"A successful response","content":{"application/json":{"schema":{"type":"object","properties":{"hex":{"type":"string","example":"02000000000102278718f8db50b78d8fd466e1c6a41155d36cb42563d51582b4eb26c8b550..."}}}}}}}}},"/utils/submit-package":{"post":{"tags":["Utils"],"summary":"submit a package of transactions to the bitcoin network","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"txHexes":{"type":"array","items":{"type":"string"},"description":"The transaction hexes in the package","example":["02000000000102278718f8db50b78d8fd466e1c6a41155d36cb42563d51582b4eb26c8b550...","02000000000102278718f8db50b78d8fd466e1c6a41155d36cb42563d51582b4eb26c8b550..."]}}}}}},"responses":{"200":{"description":"A successful response","content":{"application/json":{"schema":{"type":"object","properties":{"txid":{"type":"string","example":"f358178f7f72a07cb983da3b19097a5b8a8160b367609701d3d1c15e7f3147e4"}}}}}}}}},"/order/{orderId}":{"get":{"summary":"Retrieve an order by ID","description":"Fetches an order from the Firestore database using the provided order ID.","parameters":[{"in":"path","name":"orderId","required":true,"description":"The ID of the order to retrieve.","schema":{"type":"string","example":"1234567890abcdef"}}],"responses":{"200":{"description":"Successfully retrieved the order.","content":{"application/json":{"schema":{"type":"object","properties":{"createdAt":{"type":"integer","example":1721745751531},"accountId":{"type":"string","example":"ordinalsbot"},"feeCharge":{"type":"object","properties":{"createdAt":{"type":"integer","example":1721745751432},"additionalFee":{"type":"integer","example":23315},"amount":{"type":"integer","example":32315},"protocol":{"type":"string","example":"bitcoin"},"address":{"type":"string","example":"bc1qh3rp2pns6nrr8mhx0rlzd5kktwm33wc4ax0h4y"},"txid":{"type":"string","example":null},"state":{"type":"string","example":"pending_payment"},"token":{"type":"string","example":"BTC"}}},"description":{"type":"string","example":"e14fefbe-fc23-40a2-b0d6-6aab7bff3438"},"id":{"type":"string","example":"f2bcddd4-bd8d-4c88-bf8a-61be0d5b0600"},"state":{"type":"string","example":"pending"},"tokenCharge":{"type":"object","properties":{"createdAt":{"type":"integer","example":1721745751530},"additionalFee":{"type":"integer","example":0},"amount":{"type":"integer","example":1},"protocol":{"type":"string","example":"rune"},"address":{"type":"string","example":"bc1p76ppg0q24p2v6faxkaffrvtg0n9u2wvgjzr2g48nfnhk6z7g8wasnwtsql"},"txid":{"type":"string","example":null},"state":{"type":"string","example":"pending_payment"},"token":{"type":"string","example":"SHITCOINPARADISE"}}},"webhookUrl":{"type":"string","example":"https://webhook.site/f5a2dcec-b7e4-4845-92d1-22ded0057104"}}}}}},"404":{"description":"Order not found.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"Order not found"}}}}}}}}},"/user/order/rune":{"post":{"tags":["User"],"summary":"Create a new Rune order","description":"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.\n","parameters":[{"in":"header","name":"x-api-key","required":true,"description":"API key for authentication.","schema":{"type":"string","example":"your-api-key"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"amount":{"type":"number","description":"The amount for the order.","example":1},"token":{"type":"string","description":"The token for the order.","example":"SHITCOINPARADISE"},"webhookUrl":{"type":"string","description":"The webhook URL for the order.","example":"https://webhook.site/f5a2dcec-b7e4-4845-92d1-22ded0057104"},"additionalFee":{"type":"integer","description":"The additional fee for the order.","example":0},"description":{"type":"string","description":"The description for the order.","example":"e14fefbe-fc23-40a2-b0d6-6aab7bff3438"}}}}}},"responses":{"200":{"description":"Successfully created the order.","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","example":"b15ad7f6-b34a-4a1e-8c0f-30492610a3d6"},"createdAt":{"type":"integer","example":1730120609939},"accountId":{"type":"string","example":"ordinalsbot"},"feeCharge":{"type":"object","properties":{"amount":{"type":"integer","example":100},"token":{"type":"string","example":"BTC"},"address":{"type":"string","example":"bc1qd0a0kq9hdmem24x229s7pytgp759et7takws72"},"state":{"type":"string","example":"pending_payment"},"protocol":{"type":"string","example":"bitcoin"},"txid":{"type":"string","example":null},"createdAt":{"type":"integer","example":1730120609719},"additionalFee":{"type":"integer","example":100}}},"tokenCharge":{"type":"object","properties":{"amount":{"type":"integer","example":1},"token":{"type":"string","example":"SHITCOIN•PARADISE"},"address":{"type":"string","example":"bc1prhdced0h23ppfvqqk2pe5k092u5ncev8rmvvlz6h5kvezcd2g93qfjmg9v"},"state":{"type":"string","example":"pending_payment"},"protocol":{"type":"string","example":"rune"},"txid":{"type":"string","example":null},"createdAt":{"type":"integer","example":1730120609939},"additionalFee":{"type":"integer","example":0}}},"webhookUrl":{"type":"string","example":"https://api.ordinalsbot.com/webhook/tokenpay"},"successUrl":{"type":"string","example":null},"state":{"type":"string","example":"pending"},"description":{"type":"string","example":"56f3f01e-407b-4099-b172-591501f7129d"},"webhookSecretToken":{"type":"string","example":"c051a42521ab8d2987c3626a6246d99f8a3397cd6be626ee0eeb7f5457e92432","description":"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.\n"}}}}}},"400":{"description":"Bad request. Invalid input parameters.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"Invalid input parameters"}}}}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"Internal server error"}}}}}}}}},"/user/account/withdraw":{"post":{"tags":["User"],"summary":"Withdraw funds from user account","description":"Withdraws funds from the user's account to the specified address.","parameters":[{"in":"header","name":"x-api-key","required":true,"description":"API key for authentication.","schema":{"type":"string","example":"your-api-key"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"protocol":{"type":"string","description":"The protocol for the withdrawal.","example":"bitcoin"},"token":{"type":"string","description":"The token for the withdrawal.","example":"BTC"},"amount":{"type":"number","description":"The amount to withdraw.","example":0.5},"address":{"type":"string","description":"The address to withdraw to.","example":"bc1qh3rp2pns6nrr8mhx0rlzd5kktwm33wc4ax0h4y"}}}}}},"responses":{"200":{"description":"Successfully created the withdrawal request.","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","example":"f2bcddd4-bd8d-4c88-bf8a-61be0d5b0600"},"accountId":{"type":"string","example":"user123"},"protocol":{"type":"string","example":"bitcoin"},"token":{"type":"string","example":"BTC"},"amount":{"type":"number","example":0.5},"address":{"type":"string","example":"bc1qh3rp2pns6nrr8mhx0rlzd5kktwm33wc4ax0h4y"},"state":{"type":"string","example":"pending"},"createdAt":{"type":"integer","example":1721745751531}}}}}},"400":{"description":"Bad request. Invalid input parameters.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"Invalid input parameters"}}}}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"Internal server error"}}}}}}}}},"/user/withdrawal/{withdrawalId}":{"get":{"tags":["User"],"summary":"Get withdrawal details","description":"Retrieves the details of a specific withdrawal using the withdrawal ID.","parameters":[{"in":"header","name":"x-api-key","required":true,"description":"API key for authentication.","schema":{"type":"string","example":"your-api-key"}},{"in":"path","name":"withdrawalId","required":true,"description":"The ID of the withdrawal to retrieve.","schema":{"type":"string","example":"f2bcddd4-bd8d-4c88-bf8a-61be0d5b0600"}}],"responses":{"200":{"description":"Successfully retrieved the withdrawal details.","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","example":"f2bcddd4-bd8d-4c88-bf8a-61be0d5b0600"},"accountId":{"type":"string","example":"user123"},"protocol":{"type":"string","example":"bitcoin"},"token":{"type":"string","example":"BTC"},"amount":{"type":"number","example":0.5},"address":{"type":"string","example":"bc1qh3rp2pns6nrr8mhx0rlzd5kktwm33wc4ax0h4y"},"state":{"type":"string","example":"completed"},"createdAt":{"type":"integer","example":1721745751531}}}}}},"400":{"description":"Bad request. Invalid input parameters.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"Invalid input parameters"}}}}}},"404":{"description":"Withdrawal not found.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"Withdrawal not found"}}}}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"Internal server error"}}}}}}}}},"/user/account/balance":{"get":{"tags":["User"],"summary":"Get account balance","description":"Retrieves the balance of a specific user account.","parameters":[{"in":"header","name":"x-api-key","required":true,"description":"API key for authentication.","schema":{"type":"string","example":"your-api-key"}}],"responses":{"200":{"description":"Successfully retrieved the account balance.","content":{"application/json":{"schema":{"type":"object","properties":{"bitcoin":{"type":"object","properties":{"BTC":{"type":"number","example":0}}},"rune":{"type":"object","properties":{"XRUNE":{"type":"number","example":10}}}}}}}},"400":{"description":"Bad request. Invalid input parameters.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"Invalid input parameters"}}}}}},"404":{"description":"Account not found.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"Account not found"}}}}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"Internal server error"}}}}}}}}},"/user/account/orders":{"get":{"tags":["User"],"summary":"Get completed orders for the user","description":"Retrieves a list of completed orders for the user.","parameters":[{"in":"header","name":"x-api-key","required":true,"description":"API key for authentication.","schema":{"type":"string","example":"your-api-key"}}],"responses":{"200":{"description":"Successfully retrieved the completed orders.","content":{"application/json":{"schema":{"type":"array","items":{"type":"object","properties":{"createdAt":{"type":"integer","example":1728935970725},"accountId":{"type":"string","example":"zach"},"feeCharge":{"type":"object","properties":{"createdAt":{"type":"integer","example":1728935970590},"additionalFee":{"type":"integer","example":0},"amount":{"type":"integer","example":9000},"protocol":{"type":"string","example":"bitcoin"},"address":{"type":"string","example":"tb1q0pe77zq9vjuxlp2lvqyml97w6hjmj7sutun6zk"},"txid":{"type":"string","example":"ef4a17fad91165dbd117b80357a0af89d2eec039d3cd9e248f52f083de487bea"},"state":{"type":"string","example":"confirmed"},"token":{"type":"string","example":"BTC"}}},"successUrl":{"type":"string","nullable":true,"example":"https://some.site"},"description":{"type":"string","example":"xxx"},"id":{"type":"string","example":"8c88607e-b0fb-4b37-a0ab-a11ea1742440"},"webhookUrl":{"type":"string","example":"https://webhook.site/2337e8e3-3620-4075-a5c3-9be4ef2ca1dd"},"state":{"type":"string","example":"completed"},"tokenCharge":{"type":"object","properties":{"createdAt":{"type":"integer","example":1728935970724},"additionalFee":{"type":"integer","example":0},"amount":{"type":"integer","example":1},"protocol":{"type":"string","example":"rune"},"address":{"type":"string","example":"tb1pw3lzltp09w8jlatj9xfcjs4atudhf6706gqtcr8yj8tu0ezpjs3q2ear8d"},"txid":{"type":"string","example":"d14ea7cd91ec787f77127c2c23573940c5e79e1d643d7c2b6df804280aa6689d"},"state":{"type":"string","example":"confirmed"},"token":{"type":"string","example":"TOKENPAY•TOKEN"}}}}}}}}},"400":{"description":"Bad request. Invalid input parameters.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"Invalid input parameters"}}}}}},"404":{"description":"Account not found.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"Account not found"}}}}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"Internal server error"}}}}}}}}},"/create-payment-psbt":{"post":{"tags":["PSBT"],"summary":"Create a payment PSBT","description":"Handles the creation of a payment PSBT.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"orderId":{"type":"string","description":"The ID of the order.","example":"order123"},"paymentAddress":{"type":"string","description":"The payment address.","example":"1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa"},"paymentPublicKey":{"type":"string","description":"The payment public key.","example":"02b463a1e6b8e1a1e1a1e1a1e1a1e1a1e1a1e1a1e1a1e1a1e1a1e1a1e1a1e1a1"},"ordinalAddress":{"type":"string","description":"The ordinal address.","example":"bc1qw508d6qejxtdg4y5r3zarvary0c5xw7kygt080"},"ordinalPublicKey":{"type":"string","description":"The ordinal public key.","example":"03b463a1e6b8e1a1e1a1e1a1e1a1e1a1e1a1e1a1e1a1e1a1e1a1e1a1e1a1e1a1"},"feeRate":{"type":"number","description":"The fee rate for the transaction.","example":0.0001}}}}}},"responses":{"200":{"description":"Successfully created the payment PSBT.","content":{"application/json":{"schema":{"type":"object","properties":{"psbt":{"type":"string","description":"The created PSBT.","example":"cHNidP8BAFICAAAA..."}}}}}},"400":{"description":"Bad request. Invalid input parameters.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"Invalid input parameters"}}}}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"Internal server error"}}}}}}}}},"/create-burn-rune-psbt":{"post":{"tags":["PSBT"],"summary":"Create a burn rune PSBT","description":"Handles the creation of a burn rune PSBT.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"rune":{"type":"string","description":"The name of the rune.","example":"UNCOMMON•GOODS"},"utxo":{"type":"string","description":"utxo that includes the rune to be burned.","example":"8bfcb8240f34bdc57627ac0727fe37bb7746a104f169aad422a0ec7ad2e67cc4:0"},"paymentAddress":{"type":"string","description":"The payment address.","example":"1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa"},"paymentPublicKey":{"type":"string","description":"The payment public key.","example":"02b463a1e6b8e1a1e1a1e1a1e1a1e1a1e1a1e1a1e1a1e1a1e1a1e1a1e1a1"},"ordinalAddress":{"type":"string","description":"The ordinal address.","example":"bc1qw508d6qejxtdg4y5r3zarvary0c5xw7kygt080"},"ordinalPublicKey":{"type":"string","description":"The ordinal public key.","example":"03b463a1e6b8e1a1e1a1e1a1e1a1e1a1e1a1e1a1e1a1e1a1e1a1e1a1e1a1"},"feeRate":{"type":"number","description":"The fee rate for the transaction in sats/vbyte.","example":5}}}}}},"responses":{"200":{"description":"Successfully created the burn PSBT.","content":{"application/json":{"schema":{"type":"object","properties":{"psbt":{"type":"string","description":"The created PSBT.","example":"cHNidP8BAFICAAAA..."}}}}}},"400":{"description":"Bad request. Invalid input parameters.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"Invalid input parameters"}}}}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"Internal server error"}}}}}}}}},"/validate-burn-rune-tx":{"post":{"tags":["Utils"],"summary":"Validate a burn rune transaction","description":"Validates a burn rune transaction using the provided transaction ID.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"string","description":"The transaction ID to validate.","example":"1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef"}}}}}},"responses":{"200":{"description":"Successfully validated the transaction.","content":{"application/json":{"schema":{"type":"object","properties":{"valid":{"type":"boolean","example":true}}}}}},"400":{"description":"Bad request. Invalid input parameters.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"Invalid input parameters"}}}}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"Internal server error"}}}}}}}}},"/create-burn-inscription-psbt":{"post":{"tags":["PSBT"],"summary":"Create a burn inscription PSBT","description":"Handles the creation of a burn inscription PSBT.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"inscriptionId":{"type":"string","description":"The inscription id that needs to be burned.","example":"bcea50b5c826ebb48215d56325b46cd35511a4c6e166d48f8db750dbf8188727i63"},"utxo":{"type":"string","description":"The utxo that includes the inscription to be burned.","example":"8bfcb8240f34bdc57627ac0727fe37bb7746a104f169aad422a0ec7ad2e67cc4:0"},"paymentAddress":{"type":"string","description":"The payment address.","example":"1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa"},"paymentPublicKey":{"type":"string","description":"The payment public key.","example":"02b463a1e6b8e1a1e1a1e1a1e1a1e1a1e1a1e1a1e1a1e1a1e1a1e1a1e1a1"},"ordinalAddress":{"type":"string","description":"The ordinal address.","example":"bc1qw508d6qejxtdg4y5r3zarvary0c5xw7kygt080"},"ordinalPublicKey":{"type":"string","description":"The ordinal public key.","example":"03b463a1e6b8e1a1e1a1e1a1e1a1e1a1e1a1e1a1e1a1e1a1e1a1e1a1e1a1"},"feeRate":{"type":"number","description":"The fee rate for the transaction in sats/vbyte.","example":2},"metadata":{"type":"string","description":"The metadata to be included in the burn metadata field of the inscription.","example":"Max 80 bytes"}}}}}},"responses":{"200":{"description":"Successfully created the burn inscription PSBT.","content":{"application/json":{"schema":{"type":"object","properties":{"psbtBase64":{"type":"string","description":"The created PSBT in base64 format.","example":"cHNidP8BAFICAAAA..."},"runeInputs":{"type":"object","properties":{"indices":{"type":"array","items":{"type":"integer"},"example":[0]},"address":{"type":"string","example":"tb1pzq63cpltakkeegqaqje9zc9k5v92ud540tuwvymef4rul00y5mzqg5mvdc"}}},"paymentInputs":{"type":"object","properties":{"indices":{"type":"array","items":{"type":"integer"},"example":[1]},"address":{"type":"string","example":"2N4v1yyB5arLfQ3wHgAroRYmb49LVedkkYg"}}},"psbtHex":{"type":"string","description":"The created PSBT in hex format.","example":"70736274ff0100af02..."}}}}}},"400":{"description":"Bad request. Invalid input parameters.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"Invalid input parameters"}}}}}},"500":{"description":"Internal server error.","content":{"application/json":{"schema":{"type":"object","properties":{"error":{"type":"string","example":"Internal server error"}}}}}}}}}},"components":{},"tags":[{"name":"User","description":"Operations related to user accounts and orders"},{"name":"PSBT","description":"Operations related to PSBTs"},{"name":"Utils","description":"Utility operations"}]}