{ "openapi": "3.0.0", "info": { "title": "Blockonomics API", "version": "1.0.0", "description": "API for interacting with Blockonomics services" }, "servers": [ { "url": "https://www.blockonomics.co/api", "description": "Blockonomics' server" } ], "paths": { "/balance": { "get": { "tags": [ "Search" ], "summary": "Get confirmed and unconfirmed balance", "description": "Returns confirmed and unconfirmed balance for one or more Bitcoin addresses or xpubs. All values are in satoshis.", "security": [ { "BearerAuth": [] } ], "operationId": "getBalance", "parameters": [ { "name": "addr", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Whitespace-separated list of Bitcoin addresses and/or xpubs. A `+` or `%20` may also be used as a separator.", "example": "1JJ5taVeiHcD6DXNkLLfocbHcE9Nzio1qV xpub6CUGRUonZSQ4TWtTMmzXdrXDtypWKiKrhko4egpiMZbpiaQL2jkwSB1icqYh2cfDfVxdx4df189oLKnC5fSwqPfgyP3hooxujYzAu3fDVmz" } ], "responses": { "200": { "description": "Balance response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "response": { "type": "array", "items": { "$ref": "#/components/schemas/Balance" } } } }, "example": { "response": [ { "confirmed": 1000000, "addr": "1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa", "unconfirmed": 50000 } ] } } } }, "400": { "description": "Invalid xPub(s) or address(es) provided", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "integer", "example": 400 }, "error": { "type": "object", "properties": { "message": { "type": "string", "example": "The xPub(s) or address(es) provided are invalid" }, "invalid_input": { "type": "string", "description": "The specific xPub or address that was invalid", "example": "invalidAddress123" } } } } } } } }, "401": { "description": "This function requires you to login", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" } } } } } }, "404": { "description": "No match found for one or more of the provided xPub(s) or address(es)", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "integer", "example": 404 }, "error": { "type": "object", "properties": { "message": { "type": "string", "example": "No match found for one or more of the provided xPub(s) or address(es)" }, "not_found": { "type": "string", "description": "The specific xPub or address that was not found", "example": "1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa" } } } } } } } } } } }, "/searchhistory": { "get": { "tags": [ "Search" ], "summary": "Get transaction history for wallet addresses", "description": "Returns the transaction history for one or more Bitcoin addresses or xpubs, treated as a single wallet. Returns up to 200 transactions, sorted newest-first.", "security": [ { "BearerAuth": [] } ], "operationId": "getTransactionHistory", "parameters": [ { "name": "addr", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Space-separated list of Bitcoin addresses and/or xpubs", "examples": { "two addresses": { "summary": "twoAddresses", "value": "1JJ5taVeiHcD6DXNkLLfocbHcE9Nzio1qV 13A1W4jLPP75pzvn2qJ5KyyqG3qPSpb9jM" }, "single address": { "summary": "singleAddress", "value": "1JJ5taVeiHcD6DXNkLLfocbHcE9Nzio1qV" }, "xpub": { "summary": "extendedPublicKey", "value": "xpub6D4BDPcP2GT577Vvch3R8wDkScZWzQzMMUm3PWbmWvVJrZwQY4VUNgqFJPMM3No2dFDFGTsxxpG5uJh7n7epu4trkrX7x7DogT5Uv6fcLW5" } } }, { "name": "fiat_currency", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "USD", "EUR", "JPY", "KRW", "GBP", "AUD", "CAD", "CHF", "CNY", "INR", "AED", "AFN", "ALL", "AMD", "ANG", "AOA", "ARS", "AWG", "AZN", "BAM", "BBD", "BDT", "BGN", "BHD", "BIF", "BMD", "BND", "BOB", "BRL", "BSD", "BTN", "BWP", "BYN", "BZD", "CDF", "CLP", "COP", "CRC", "CUP", "CVE", "CZK", "DJF", "DKK", "DOP", "DZD", "EGP", "ETB", "EUR", "FJD", "FKP", "GEL", "GHS", "GIP", "GMD", "GNF", "GTQ", "GYD", "HKD", "HNL", "HRK", "HTG", "HUF", "IDR", "ILS", "INR", "IQD", "IRR", "ISK", "JEP", "JMD", "JOD", "JPY", "KES", "KGS", "KHR", "KMF", "KPW", "KRW", "KWD", "KYD", "KZT", "LAK", "LBP", "LKR", "LRD", "LSL", "LYD", "MAD", "MDL", "MGA", "MKD", "MMK", "MNT", "MOP", "MRU", "MUR", "MVR", "MWK", "MXN", "MYR", "MZN", "NAD", "NGN", "NIO", "NOK", "NPR", "NZD", "OMR", "PAB", "PEN", "PGK", "PHP", "PKR", "PLN", "PYG", "QAR", "RON", "RSD", "RUB", "RWF", "SAR", "SBD", "SCR", "SDG", "SEK", "SGD", "SHP", "SLL", "SOS", "SRD", "STN", "SVC", "SYP", "SZL", "THB", "TJS", "TMT", "TND", "TOP", "TRY", "TTD", "TWD", "TZS", "UAH", "UGX", "USD", "UYU", "UZS", "VES", "VND", "VUV", "WST", "XAF", "XAG", "XAU", "XCD", "XOF", "XPF", "YER", "ZAR", "ZMW", "ZWL" ], "default": "USD" }, "description": "Fiat currency code. When provided, confirmed transactions include a `fiat_value_at_transaction_time` field with the historical fiat equivalent.", "example": "USD" } ], "responses": { "200": { "description": "Transaction history grouped by confirmation status", "content": { "application/json": { "schema": { "type": "object", "required": [ "pending", "history" ], "properties": { "pending": { "type": "array", "description": "Unconfirmed transactions (< 2 confirmations).", "items": { "$ref": "#/components/schemas/Transaction" } }, "history": { "type": "array", "description": "Confirmed transactions (2+ confirmations).", "items": { "$ref": "#/components/schemas/Transaction" } } } }, "examples": { "with_fiat": { "summary": "With fiat currency", "value": { "history": [ { "txid": "12ba61bd280a4042576b58160223447c8ab2a17557b1a0bc2c8bd3586f46069a", "addr": [ "bc1qy5aaxp270epvhga0fud8q2jv4xzhmgmjllmep2" ], "value": -16209, "time": 1640995200, "fiat_value_at_transaction_time": 0.72 } ], "pending": [ { "txid": "d63a82046023b09bdca496b6a510463fb56a5b062e86855e919a1c8ec8ec4648", "value": -440, "time": 1640998368, "status": 1, "fee": 440, "size": 110, "conf_time": 10, "addr": [ "bc1qqqdn48ayae2cvlyafycrjmzvlmxcaxz3am3000", "bc1qy5aaxp270epvhga0fud8q2jv4xzhmgmjllmep2" ] } ] } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "integer", "example": 400 }, "error": { "type": "object", "properties": { "message": { "type": "string", "description": "Human-readable error message" }, "code": { "type": "integer", "description": "Error code for programmatic handling" } } } } }, "examples": { "invalid_xpub": { "summary": "Invalid extended public key", "value": { "status": 400, "error": { "message": "Invalid Extended Public Key", "code": 1018 } } } } } } } } } }, "/tx_detail": { "get": { "tags": [ "Search" ], "summary": "Get transaction details", "description": "Returns full details for a Bitcoin transaction including inputs, outputs, fee, size, and RBF status.", "security": [ { "BearerAuth": [] } ], "operationId": "getTransactionDetails", "parameters": [ { "name": "txid", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Transaction ID", "example": "c4978bfc9b4cd632fb37eb5f69c7c686ae364d9cb1b32ec01c0f8bae72530a4e" } ], "responses": { "200": { "description": "Transaction details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransactionDetail" }, "example": { "txid": "c4978bfc9b4cd632fb37eb5f69c7c686ae364d9cb1b32ec01c0f8bae72530a4e", "status": "Confirmed", "fee_usd": 106.359, "conf_time": 0, "rbf": "", "value": 0, "size": 257, "time": 1577166893, "vin": [ { "value": 5724464598, "address": "1AEgdWjJrEbroURgWmPrXkFdzxGxdF7c4G" } ], "vout": [ { "value": 10000, "address": "1FnQjXQc8F6jyjF8L92yLpnMhSWpw8t8jo" }, { "value": 4824404598, "address": "1AEgdWjJrEbroURgWmPrXkFdzxGxdF7c4G" }, { "value": 899950000, "address": "33wBKF7y471qK9zuWQDHbesnGX8JL5YCbW" } ], "args_txin": [ { "address": "1AEgdWjJrEbroURgWmPrXkFdzxGxdF7c4G", "value": "57.24464598", "highlight": false } ], "args_txout": [ { "address": "1FnQjXQc8F6jyjF8L92yLpnMhSWpw8t8jo", "value": "0.0001", "highlight": false }, { "address": "1AEgdWjJrEbroURgWmPrXkFdzxGxdF7c4G", "value": "48.24404598", "highlight": false }, { "address": "33wBKF7y471qK9zuWQDHbesnGX8JL5YCbW", "value": "8.9995", "highlight": false } ] } } } } } } }, "/op_return": { "get": { "tags": [ "Search" ], "summary": "Search OP_RETURN data", "description": "Search Bitcoin transactions by their OP_RETURN payload. Returns matching transactions with their transaction ID, timestamp, and embedded data.", "operationId": "searchOpReturn", "parameters": [ { "name": "q", "in": "query", "required": true, "schema": { "type": "string", "minLength": 2 }, "description": "Search string to match against OP_RETURN data.", "example": "eternalnote" }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 200 }, "description": "Maximum number of results to return." } ], "responses": { "200": { "description": "Matching transactions", "content": { "application/json": { "schema": { "type": "object", "properties": { "response": { "type": "array", "items": { "$ref": "#/components/schemas/OpReturn" } } } } } } }, "400": { "description": "Invalid query (too short or limit out of range)", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "example": "Search query must be at least 2 characters" } } } } } } } } }, "/v2/wallets": { "get": { "tags": [ "Wallets" ], "summary": "List all wallets", "description": "Returns a list of all wallets associated with your Blockonomics account.", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "balance", "in": "query", "schema": { "type": "boolean", "default": false }, "description": "Whether to include balance information" } ], "responses": { "200": { "description": "List of wallets", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WalletsResponse" } } } } } }, "post": { "tags": [ "Wallets" ], "summary": "Add a wallet", "description": "Attach a new wallet to your Blockonomics account.", "security": [ { "BearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "address", "crypto" ], "properties": { "name": { "type": "string", "description": "Name your wallet for easier identification" }, "address": { "type": "string", "description": "Wallet address. For BTC: xPub address. For USDT: EVM address (0x...)." }, "crypto": { "type": "string", "enum": [ "BTC", "USDT" ], "description": "Type of crypto. Supported values: BTC, USDT." } } }, "examples": { "btcWallet": { "summary": "BTC wallet", "value": { "name": "API Wallet", "address": "xpub6CUGRUonZSQ4TWtTMmzXdrXDtypWKiKrhko4egpiMZbpiaQL2jkwSB1icqYh2cfDfVxdx4df189oLKnC5fSwqPfgyP3hooxujYzAu3fDVmz", "crypto": "BTC" } }, "usdtWallet": { "summary": "USDT wallet", "value": { "name": "API Wallet", "address": "0x742d35Cc6634C0532925a3b844Bc454e4438f44e", "crypto": "USDT" } } } } } }, "responses": { "200": { "description": "Wallet created successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WalletResponse" } } } } } } }, "/v2/wallets/{id}": { "get": { "tags": [ "Wallets" ], "summary": "Get wallet details", "description": "Returns details of a specific wallet.", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "The unique ID of the wallet" }, { "name": "balance", "in": "query", "schema": { "type": "boolean", "default": false }, "description": "Whether to include balance information" } ], "responses": { "200": { "description": "Wallet details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WalletResponse" } } } } } }, "post": { "tags": [ "Wallets" ], "summary": "Update a wallet", "description": "Update the details of a specific wallet.", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "The unique ID of the wallet" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "Give a new name to the wallet" }, "gap_limit": { "type": "integer", "description": "The number of unused addresses to check before considering the wallet as inactive. Do not touch this unless you know what you are doing." } }, "example": { "name": "Updated Wallet Name" } } } } }, "responses": { "200": { "description": "Wallet updated successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WalletResponse" } } } } } }, "delete": { "tags": [ "Wallets" ], "summary": "Delete a wallet", "description": "Remove a wallet from your Blockonomics account.", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "The unique ID of the wallet" } ], "responses": { "200": { "description": "Wallet deleted successfully" } } } }, "/v2/stores": { "get": { "tags": [ "Stores" ], "summary": "List all stores", "description": "Returns a list of all stores associated with your Blockonomics account.", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "wallets", "in": "query", "schema": { "type": "boolean", "default": false }, "description": "Whether to include details of attached wallets" } ], "responses": { "200": { "description": "List of stores", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StoresResponse" } } } } } }, "post": { "tags": [ "Stores" ], "summary": "Create a new store", "description": "Create a new store in your Blockonomics account.", "security": [ { "BearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "http_callback" ], "properties": { "name": { "type": "string", "description": "Name of the store" }, "http_callback": { "type": "string", "description": "Website's callback URL" } }, "example": { "name": "My Store", "http_callback": "https://www.example.com/api/merchant_callback?secret=1234567890" } } } } }, "responses": { "200": { "description": "Store created successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StoreResponse" } } } } } } }, "/v2/stores/{id}": { "get": { "tags": [ "Stores" ], "summary": "Get store details", "description": "Returns details of a specific store.", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "The unique ID of the store" } ], "responses": { "200": { "description": "Store details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StoreResponse" } } } } } }, "post": { "tags": [ "Stores" ], "summary": "Update a store", "description": "Update the details of a specific store.", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "The unique ID of the store" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "New name for the store" }, "http_callback": { "type": "string", "description": "New callback URL for the store" } }, "example": { "name": "Updated Store Name", "http_callback": "https://www.example.com/api/merchant_callback?secret=1234567890" } } } } }, "responses": { "200": { "description": "Store updated successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StoreResponse" } } } } } }, "delete": { "tags": [ "Stores" ], "summary": "Delete store", "description": "Delete a store from your Blockonomics account.", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "The unique ID of the store" } ], "responses": { "200": { "description": "Store deleted successfully" } } } }, "/v2/stores/{id}/wallets": { "get": { "tags": [ "Stores" ], "summary": "Get store wallets", "description": "Returns a list of wallets attached to a specific store.", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "The unique ID of the store" } ], "responses": { "200": { "description": "List of store wallets", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WalletsResponse" } } } } } }, "post": { "tags": [ "Stores" ], "summary": "Attach wallet to store", "description": "Attach an existing wallet in your Blockonomics account to a specific store.", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "The unique ID of the store" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "wallet_id" ], "properties": { "wallet_id": { "type": "integer", "description": "The unique ID of the wallet to attach" } } } } } }, "responses": { "200": { "description": "Wallet attached successfully" } } } }, "/v2/stores/{id}/wallets/{wallet_id}": { "delete": { "tags": [ "Stores" ], "summary": "Detach wallet from store", "description": "Detach a wallet from a specific store.", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "The unique ID of the store" }, { "name": "wallet_id", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "The unique ID of the wallet to detach" } ], "responses": { "200": { "description": "Wallet detached successfully" } } } }, "/new_address": { "post": { "tags": [ "Merchants" ], "summary": "Create or Get Payment Address", "description": "Generates a new payment address to receive payment on your store.", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "match_callback", "in": "query", "required": false, "schema": { "type": "string" }, "description": "String to match part of your store's callback URL. Used to identify the correct store when you have multiple. Partial matches are supported — you don’t need to provide the full callback URL." }, { "name": "crypto", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "BTC", "USDT" ], "default": "BTC" }, "description": "Cryptocurrency to use. When USDT, the same address is always returned." }, { "name": "reset", "in": "query", "required": false, "schema": { "type": "integer", "enum": [ 0, 1 ], "default": 0, "example": 1 }, "description": "Controls address generation for BTC. `0` (default) = new address, `1` = reuse last address. Ignored for USDT." } ], "responses": { "200": { "description": "Payment address generated successfully.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentAddress" }, "examples": { "BTC": { "summary": "BTC example", "value": { "address": "1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa", "crypto": "BTC", "reset": 0, "account": "btc_xpub_wallet" } }, "USDT": { "summary": "USDT example", "value": { "address": "0x0c1EA7FDCA81357658904d9fa6Da730c3ba19B26", "crypto": "USDT", "reset": 0, "account": "usdt_wallet" } } } } } }, "400": { "description": "Bad request", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string", "description": "Error message describing what went wrong." } } }, "example": { "error": "Invalid request." } } } }, "409": { "description": "Conflict – Required wallet not attached to store", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "integer", "description": "HTTP status code" }, "error": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" }, "code": { "type": "integer", "description": "Application-specific error code" } } } } }, "example": { "status": 409, "error": { "message": "Please attach the required wallet to the store. No wallet of type BTC attached to the store.", "code": 1041 } } } } }, "422": { "description": "Unsupported Cryptocurrency", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "integer", "description": "HTTP status code" }, "error": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" }, "code": { "type": "integer", "description": "Application-specific error code" } } } } }, "example": { "status": 422, "error": { "message": "Unsupported cryptocurrency provided. Only BTC and USDT are supported.", "code": 1042 } } } } } } } }, "/price": { "get": { "tags": [ "Merchants" ], "summary": "Fetch cryptocurrency price", "description": "Returns the current price of 1 unit of the specified cryptocurrency in a given fiat currency. All supported fiat currencies are listed [here](https://www.blockonomics.co/api/currencies).", "parameters": [ { "name": "crypto", "in": "query", "description": "Cryptocurrency code for which the price is returned per 1 unit.", "required": false, "schema": { "type": "string", "enum": [ "BTC", "USDT", "BCH", "ETH", "SOL", "XRP", "MATIC", "LTC" ], "default": "BTC" }, "examples": { "btc": { "summary": "Bitcoin", "value": "BTC" }, "bch": { "summary": "Bitcoin Cash", "value": "BCH" }, "eth": { "summary": "Ethereum", "value": "ETH" }, "usdt": { "summary": "Tether", "value": "USDT" }, "sol": { "summary": "Solana", "value": "SOL" }, "xrp": { "summary": "Ripple", "value": "XRP" }, "matic": { "summary": "Polygon", "value": "MATIC" }, "ltc": { "summary": "Litecoin", "value": "LTC" } } }, { "name": "currency", "in": "query", "description": "Fiat currency code to return the price in.", "required": true, "schema": { "type": "string", "enum": [ "USD", "EUR", "JPY", "KRW", "GBP", "AUD", "CAD", "CHF", "CNY", "INR", "AED", "AFN", "ALL", "AMD", "ANG", "AOA", "ARS", "AWG", "AZN", "BAM", "BBD", "BDT", "BGN", "BHD", "BIF", "BMD", "BND", "BOB", "BRL", "BSD", "BTN", "BWP", "BYN", "BZD", "CDF", "CLP", "COP", "CRC", "CUP", "CVE", "CZK", "DJF", "DKK", "DOP", "DZD", "EGP", "ETB", "EUR", "FJD", "FKP", "GEL", "GHS", "GIP", "GMD", "GNF", "GTQ", "GYD", "HKD", "HNL", "HRK", "HTG", "HUF", "IDR", "ILS", "INR", "IQD", "IRR", "ISK", "JEP", "JMD", "JOD", "JPY", "KES", "KGS", "KHR", "KMF", "KPW", "KRW", "KWD", "KYD", "KZT", "LAK", "LBP", "LKR", "LRD", "LSL", "LYD", "MAD", "MDL", "MGA", "MKD", "MMK", "MNT", "MOP", "MRU", "MUR", "MVR", "MWK", "MXN", "MYR", "MZN", "NAD", "NGN", "NIO", "NOK", "NPR", "NZD", "OMR", "PAB", "PEN", "PGK", "PHP", "PKR", "PLN", "PYG", "QAR", "RON", "RSD", "RUB", "RWF", "SAR", "SBD", "SCR", "SDG", "SEK", "SGD", "SHP", "SLL", "SOS", "SRD", "STN", "SVC", "SYP", "SZL", "THB", "TJS", "TMT", "TND", "TOP", "TRY", "TTD", "TWD", "TZS", "UAH", "UGX", "USD", "UYU", "UZS", "VES", "VND", "VUV", "WST", "XAF", "XAG", "XAU", "XCD", "XOF", "XPF", "YER", "ZAR", "ZMW", "ZWL" ], "default": "USD" } } ], "responses": { "200": { "description": "Current price of 1 unit of the specified cryptocurrency in the specified fiat currency.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Price" }, "examples": { "sample": { "summary": "Example price response", "value": { "price": 127866.85 } } } } } }, "400": { "description": "Missing required parameter", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "integer", "description": "HTTP status code" }, "error": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" }, "code": { "type": "integer", "description": "Application-specific error code" } } } } }, "example": { "status": 400, "error": { "message": "Missing parameter: currency is required", "code": 1068 } } } } }, "404": { "description": "No price data available for the specified currency/crypto pair", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "integer", "description": "HTTP status code" }, "error": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" }, "code": { "type": "integer", "description": "Application-specific error code" } } } } }, "example": { "status": 404, "error": { "message": "No price data available for the specified currency/crypto pair", "code": 1070 } } } } }, "422": { "description": "Unsupported fiat currency or crypto code provided", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "integer", "description": "HTTP status code" }, "error": { "type": "object", "properties": { "message": { "type": "string", "description": "Error message" }, "code": { "type": "integer", "description": "Application-specific error code" } } } } }, "example": { "status": 422, "error": { "message": "Unsupported fiat currency or crypto code provided", "code": 1069 } } } } } } } }, "/merchant_orders": { "get": { "tags": [ "Payment Buttons and Checkouts" ], "summary": "Get all orders", "description": "Returns all payment button orders for your account.", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "limit", "in": "query", "description": "The number of records to return", "required": false, "schema": { "type": "integer", "default": 500 } } ], "responses": { "200": { "description": "Order list response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "response": { "type": "array", "items": { "$ref": "#/components/schemas/OrderResponse" } } } } } } } } } }, "/merchant_order/{uuid}": { "get": { "tags": [ "Payment Buttons and Checkouts" ], "summary": "Get order details", "description": "Returns details of a specific payment button order.", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "uuid", "in": "path", "description": "The unique identifier of the order", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Details of the payment button order", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrderResponse" } } } } } } }, "/monitor_tx": { "post": { "tags": [ "Merchants" ], "summary": "Monitor USDT Transaction", "description": "Begin tracking a USDT transaction. Callbacks are sent to your store's endpoint whenever the transaction status changes.", "security": [ { "BearerAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "txhash", "crypto", "match_callback", "testnet" ], "properties": { "txhash": { "type": "string", "description": "The transaction hash to monitor.", "example": "0x712f876339d877e7558f25b4c0b684c5e1d1a11472d407a175c231894b280714" }, "crypto": { "type": "string", "enum": [ "USDT" ], "description": "The cryptocurrency used (USDT)." }, "match_callback": { "type": "string", "description": "String to match part of your store's callback URL. Used to identify the correct store when you have multiple.", "example": "www.example.com" }, "testnet": { "type": "integer", "enum": [ 0, 1 ], "default": 0, "description": "Network. `0` = mainnet (Ethereum), `1` = Sepolia testnet." } } } } } }, "responses": { "200": { "description": "Transaction successfully monitored.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "integer", "enum": [ -1, 0, 1, 2 ], "description": "Current status of the transaction. `-1` = Reverted, `0` = Unconfirmed, `1` = 1 confirmation, `2` = 2 confirmations (final)." } } }, "example": { "status": 0 } } } } } } }, "/v2/payments": { "get": { "tags": [ "Merchants" ], "summary": "Get payment history", "description": "Returns confirmed payments received across all stores, ordered newest-first.", "operationId": "getPayments", "security": [ { "BearerAuth": [] } ], "parameters": [ { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 200 }, "description": "Maximum number of payments to return (1–200). Defaults to 200." }, { "name": "timeframe", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "1W", "2W", "1M", "3M", "6M", "1Y" ], "default": "1M" }, "description": "Time window to filter payments. `1W` = 1 week, `2W` = 2 weeks, `1M` = 1 month, `3M` = 3 months, `6M` = 6 months, `1Y` = 1 year." }, { "name": "crypto", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "BTC", "BCH", "USDT" ] }, "description": "Filter by cryptocurrency. Omit to return all cryptocurrencies." }, { "name": "store_name", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Partial case-insensitive store name filter.", "example": "my store" }, { "name": "currency", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Fiat currency code (e.g. `USD`). When provided, each payment includes a `fiat_value` field with the historical fiat equivalent.", "example": "USD" } ], "responses": { "200": { "description": "List of payments", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaymentsResponse" }, "example": { "data": [ { "id": 42, "timestamp": 1700000000, "crypto": "BTC", "amount": 500000, "address": "bc1qxy2kgdygjrsqtzq2n0yrf2493p83kkfjhx0wlh", "txid": "c4978bfc9b4cd632fb37eb5f69c7c686ae364d9cb1b32ec01c0f8bae72530a4e", "store_name": "My Shop", "store_url": "https://example.com/callback", "fiat_value": 18.5 } ] } } } }, "400": { "description": "Invalid parameter (limit out of range, unsupported crypto, or invalid timeframe)" }, "401": { "description": "Authentication required" } } } } }, "components": { "securitySchemes": { "BearerAuth": { "type": "http", "scheme": "bearer", "description": "Enter your API key as the bearer token" } }, "schemas": { "Transaction": { "type": "object", "properties": { "status": { "type": "integer", "description": "Is returned only if transaction not confirmed. 0 = unconfirmed; 1 = partially confirmed", "example": 1 }, "addr": { "type": "array", "items": { "type": "string" }, "description": "List of addresses involved", "example": [ "1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa" ] }, "time": { "type": "integer", "description": "Unix timestamp", "example": 1612137600 }, "value": { "type": "integer", "description": "Value transacted in satoshis", "example": 1000000 }, "txid": { "type": "string", "description": "Transaction ID", "example": "7b9d555f0db5c547cb5644e8d6e6cd10" }, "fiat_value_at_transaction_time": { "type": "number", "description": "Fiat value of the transaction at the time it occurred (only included when fiat_currency parameter is provided in the request)", "example": 450.75 }, "fee": { "type": "integer", "description": "Network fee in satoshis (only present for pending/unconfirmed transactions).", "example": 440 }, "size": { "type": "integer", "description": "Transaction size in bytes (only present for pending/unconfirmed transactions).", "example": 110 }, "conf_time": { "type": "integer", "description": "Estimated confirmation time in minutes (only present for pending/unconfirmed transactions).", "example": 10 } } }, "TransactionDetail": { "type": "object", "properties": { "size": { "type": "integer", "description": "Transaction size in bytes", "example": 225 }, "time": { "type": "integer", "description": "Unix timestamp", "example": 1612137600 }, "vin": { "type": "array", "description": "Transaction inputs", "items": { "type": "object", "properties": { "value": { "type": "integer", "description": "Input value in satoshis", "example": 5724464598 }, "address": { "type": "string", "description": "Input address", "example": "1AEgdWjJrEbroURgWmPrXkFdzxGxdF7c4G" } } } }, "vout": { "type": "array", "description": "Transaction outputs", "items": { "type": "object", "properties": { "value": { "type": "integer", "description": "Output value in satoshis", "example": 10000 }, "address": { "type": "string", "description": "Output address", "example": "1FnQjXQc8F6jyjF8L92yLpnMhSWpw8t8jo" } } } }, "txid": { "type": "string", "description": "Transaction ID", "example": "c4978bfc9b4cd632fb37eb5f69c7c686ae364d9cb1b32ec01c0f8bae72530a4e" }, "status": { "type": "string", "description": "Transaction status", "example": "confirmed" }, "fee": { "type": "integer", "description": "Transaction fee in satoshis", "example": 100000 }, "fee_usd": { "type": "number", "description": "Transaction fee in USD", "example": 106.359 }, "conf_time": { "type": "integer", "description": "Confirmation time in seconds", "example": 0 }, "rbf": { "type": "string", "description": "Replace-By-Fee status", "example": "" }, "value": { "type": "integer", "description": "Transaction value in satoshis", "example": 0 }, "args_txin": { "type": "array", "description": "List of transaction input details", "items": { "type": "object", "properties": { "address": { "type": "string", "description": "Input address", "example": "1AEgdWjJrEbroURgWmPrXkFdzxGxdF7c4G" }, "value": { "type": "string", "description": "Input value in BTC", "example": "57.24464598" }, "highlight": { "type": "boolean", "description": "Highlight status", "example": false } } } }, "args_txout": { "type": "array", "description": "List of transaction output details", "items": { "type": "object", "properties": { "address": { "type": "string", "description": "Output address", "example": "1FnQjXQc8F6jyjF8L92yLpnMhSWpw8t8jo" }, "value": { "type": "string", "description": "Output value in BTC", "example": "0.0001" }, "highlight": { "type": "boolean", "description": "Highlight status", "example": false } } } } } }, "Wallet": { "type": "object", "properties": { "id": { "type": "integer", "description": "Unique identifier of the wallet" }, "name": { "type": "string", "description": "Given name" }, "emailid": { "type": "string", "description": "Email of the wallet owner" }, "crypto": { "type": "string", "description": "Cryptocurrency of the wallet" }, "address": { "type": "string", "description": "Address of the wallet" }, "xpub_index": { "type": "integer", "description": "The current xPub index for BTC wallet" }, "gap_limit": { "type": "integer", "description": "The gap limit for BTC wallet" }, "created_at": { "type": "string", "format": "date-time", "description": "Datetime of the wallet creation" }, "balance": { "type": "object", "description": "Aggregate wallet balance (only present when balance=true is requested).", "properties": { "confirmed_sats": { "type": "integer", "description": "Confirmed balance in satoshis." }, "unconfirmed_sats": { "type": "integer", "description": "Unconfirmed balance in satoshis." }, "confirmed_fiat": { "type": "number", "description": "Confirmed balance in fiat currency." }, "unconfirmed_fiat": { "type": "number", "description": "Unconfirmed balance in fiat currency." }, "fiat_currency": { "type": "string", "description": "Fiat currency code." }, "total_addresses": { "type": "integer", "description": "Total number of derived addresses." } } } } }, "Balance": { "type": "object", "description": "Confirmed and unconfirmed balance for a single Bitcoin address or xpub.", "properties": { "confirmed": { "type": "integer", "description": "Confirmed balance in satoshis.", "example": 1000000 }, "addr": { "type": "string", "description": "The Bitcoin address or xpub.", "example": "1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa" }, "unconfirmed": { "type": "integer", "description": "Unconfirmed balance in satoshis (< 2 confirmations).", "example": 50000 } } }, "Store": { "type": "object", "properties": { "id": { "type": "integer", "description": "Unique identifier of the store" }, "name": { "type": "string", "description": "Given name" }, "emailid": { "type": "string", "description": "Email of the store owner" }, "http_callback": { "type": "string", "description": "Callback URL of the store" }, "wallets": { "type": "array", "items": { "$ref": "#/components/schemas/Wallet" } } } }, "WalletResponse": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Wallet" } } }, "WalletsResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Wallet" } } } }, "StoreResponse": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/Store" } } }, "StoresResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Store" } } } }, "PriceResponse": { "type": "object", "properties": { "price": { "type": "number", "description": "Current price of the cryptocurrency in the specified currency", "example": 127866.85 } }, "required": [ "price" ] }, "Price": { "type": "object", "description": "The current price of 1 unit of a cryptocurrency in a specified fiat currency.", "properties": { "price": { "type": "number", "description": "Current price of the cryptocurrency in the specified fiat currency.", "example": 61367.5 } }, "required": [ "price" ] }, "OpReturn": { "type": "object", "description": "A Bitcoin transaction containing an OP_RETURN output, used to embed arbitrary data on-chain.", "properties": { "txid": { "type": "string", "description": "Transaction ID on the Bitcoin blockchain.", "example": "dd2f770fcc53e307c829158fc87771b9f0dc623a3389318897ae8cd67a390eda" }, "time": { "type": "integer", "description": "Unix timestamp of the transaction.", "example": 1783040542 }, "op_return": { "type": "string", "description": "The OP_RETURN payload embedded in the transaction output.", "example": "pwm1:m:Hello World" }, "vout": { "type": "integer", "description": "Output index of the OP_RETURN within the transaction.", "example": 2 } } }, "PaymentAddress": { "type": "object", "description": "A payment address returned when creating a new BTC or USDT payment address for your store.", "properties": { "address": { "type": "string", "description": "Generated payment address.", "example": "1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa" }, "crypto": { "type": "string", "description": "The cryptocurrency used for the address (BTC or USDT).", "example": "BTC" }, "reset": { "type": "integer", "description": "Indicates if the address index was reset (0 = new address, 1 = reuse last address).", "example": 0 }, "account": { "type": "string", "description": "The source xPub or wallet identifier.", "example": "btc_xpub_wallet" } } }, "Payment": { "type": "object", "description": "A confirmed payment received by one of your stores.", "properties": { "id": { "type": "integer", "description": "Internal payment ID.", "example": 42 }, "timestamp": { "type": "integer", "description": "Unix timestamp when the payment was received.", "example": 1700000000 }, "crypto": { "type": "string", "description": "Cryptocurrency used for the payment.", "example": "BTC" }, "amount": { "type": "integer", "description": "Payment amount in the smallest unit (satoshis for BTC).", "example": 500000 }, "address": { "type": "string", "description": "Receiving address.", "example": "bc1qxy2kgdygjrsqtzq2n0yrf2493p83kkfjhx0wlh" }, "txid": { "type": "string", "description": "Transaction ID on the blockchain.", "example": "c4978bfc9b4cd632fb37eb5f69c7c686ae364d9cb1b32ec01c0f8bae72530a4e" }, "store_name": { "type": "string", "description": "Name of the store that received the payment.", "example": "My Shop" }, "store_url": { "type": "string", "description": "Callback URL of the store.", "example": "https://example.com/callback" }, "fiat_value": { "type": "number", "description": "Historical fiat value at time of payment (only present when the `currency` parameter is supplied).", "example": 18.5 } } }, "PaymentsResponse": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Payment" } } } }, "WebSocketEvent": { "type": "object", "description": "A real-time event sent over a WebSocket connection when a payment is detected or its confirmation status changes.", "properties": { "status": { "type": "integer", "description": "Confirmation status of the transaction. 0 = Unconfirmed (in mempool), 1 = Partially confirmed (1 block), 2 = Confirmed (2+ blocks).", "example": 2 }, "timestamp": { "type": "integer", "description": "Unix timestamp of the transaction.", "example": 1470371749 }, "value": { "type": "integer", "description": "Payment amount in satoshis (100,000,000 satoshis = 1 BTC).", "example": 167377096 }, "txid": { "type": "string", "description": "Transaction ID on the Bitcoin blockchain.", "example": "aed36253434b90e45ded86ccf1729f5d2acd78bd7665c54e62d5000035a8f6d8" } } }, "CallbackEvent": { "type": "object", "description": "Query parameters sent as an HTTP GET request to your store's callback URL when a payment status changes.", "properties": { "addr": { "type": "string", "description": "The Bitcoin address that received the payment.", "example": "1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa" }, "status": { "type": "integer", "description": "Confirmation status. 0 = Unconfirmed, 1 = 1 confirmation, 2 = 2+ confirmations (final).", "example": 2 }, "value": { "type": "integer", "description": "Amount received in satoshis.", "example": 500000 }, "txid": { "type": "string", "description": "Transaction ID on the blockchain.", "example": "c4978bfc9b4cd632fb37eb5f69c7c686ae364d9cb1b32ec01c0f8bae72530a4e" }, "rbf": { "type": "integer", "description": "Only present on unconfirmed transactions using Replace-By-Fee. If present, treat the transaction as potentially reversible.", "example": 1 } } }, "OrderResponse": { "type": "object", "properties": { "code": { "type": "string", "description": "Product code" }, "xpub": { "type": "string", "description": "Extended public key of the wallet" }, "timestamp": { "type": "integer", "description": "Unix timestamp of the order" }, "currency": { "type": "string", "description": "Currency used to price the order" }, "name": { "type": "string", "description": "Name of the product" }, "status": { "type": "integer", "description": "Status of the order" }, "data": { "type": "object", "description": "Additional customer data", "properties": { "emailid": { "type": "string", "description": "Customer email ID" }, "name": { "type": "string", "description": "Customer name" }, "address": { "type": "string", "description": "Customer address" }, "phone": { "type": "string", "description": "Customer phone number" }, "Custom Field1": { "type": "string", "description": "Custom field 1" }, "Custom Field2": { "type": "string", "description": "Custom field 2" } } }, "emailid": { "type": "string", "description": "Merchant email ID" }, "order_id": { "type": "string", "description": "Unique identifier for the order" }, "address": { "type": "string", "description": "Bitcoin address for the payment" }, "value": { "type": "integer", "description": "Order value in fiat currency" }, "description": { "type": "string", "description": "Order description" }, "satoshi": { "type": "integer", "description": "Order value in satoshis" }, "txid": { "type": "string", "nullable": true, "description": "Transaction ID if payment is made" }, "paid_satoshi": { "type": "integer", "description": "Amount paid in satoshis" } } }, "USDTTransaction": { "type": "object", "description": "A USDT transaction monitoring request to track status changes and receive callbacks.", "properties": { "txhash": { "type": "string", "description": "The transaction hash to monitor on the Ethereum blockchain.", "example": "0x712f876339d877e7558f25b4c0b684c5e1d1a11472d407a175c231894b280714" }, "crypto": { "type": "string", "description": "The cryptocurrency being monitored.", "enum": [ "USDT" ], "example": "USDT" }, "match_callback": { "type": "string", "description": "String to match part of your Store callback URL. Used when you have multiple stores to ensure the correct one is matched.", "example": "www.example.com" }, "testnet": { "type": "integer", "description": "Indicates if the transaction is on the testnet. 0 = mainnet (Ethereum), 1 = sepolia testnet. Defaults to 0 if omitted.", "enum": [ 0, 1 ], "example": 0 } }, "required": [ "txhash", "crypto", "match_callback", "testnet" ] } } } }