BlockonomicsAPI Reference

Merchants

Generate payment addresses, track incoming payments, monitor USDT transactions, and fetch live Bitcoin prices.

4 endpoints

Endpoints

Create or Get Payment Address
POST/new_address
Fetch cryptocurrency price
GET/price
Monitor USDT Transaction
POST/monitor_tx
Get payment history
GET/v2/payments
object

The payment_address object

A payment address returned when creating a new BTC or USDT payment address for your store.

Attributes

addressstring

Generated payment address.

cryptostring

The cryptocurrency used for the address (BTC or USDT).

resetinteger

Indicates if the address index was reset (0 = new address, 1 = reuse last address).

accountstring

The source xPub or wallet identifier.

Example object

{
  "address": "1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa",
  "crypto": "BTC",
  "reset": 0,
  "account": "btc_xpub_wallet"
}
POST/new_addressAuth required

Create or Get Payment Address

Generates a new payment address to receive payment on your store.

Requires Bearer token authentication. Include Authorization: Bearer YOUR_API_KEY in the request header.

Query Parameters

match_callbackstringrequired

String used to match part of your callback URL to identify the correct wallet. Partial matches are supported — you don’t need to provide the full callback URL.

cryptostring enumdefault: "BTC"

Cryptocurrency to use. When USDT, the same address is always returned.

"BTC""USDT"
resetinteger enumdefault: 0

Controls address generation for BTC. 0 (default) = new address, 1 = reuse last address. Ignored for USDT.

01

Responses

Returns a payment-address object
match_callbackquery · stringrequired

String used to match part of your callback URL to identify the correct wallet. Partial matches are supported — you don’t need to provide the full callback URL.

cryptoquery · string

Cryptocurrency to use. When USDT, the same address is always returned.

resetquery · integer

Controls address generation for BTC. `0` (default) = new address, `1` = reuse last address. Ignored for USDT.

Response will appear here

object

The price object

The current price of 1 unit of a cryptocurrency in a specified fiat currency.

Attributes

pricenumberrequired

Current price of the cryptocurrency in the specified fiat currency.

Example object

{
  "price": 61367.5
}
GET/price

Fetch cryptocurrency price

Returns the current price of 1 unit of the specified cryptocurrency in a given fiat currency. All supported fiat currencies are listed here.

Query Parameters

cryptostring enumdefault: "BTC"

Cryptocurrency code for which the price is returned per 1 unit.

"BTC""USDT""BCH""ETH""SOL""XRP""MATIC""LTC"
currencystring enumrequireddefault: "USD"

Fiat currency code to return the price in.

Responses

Returns a price object
cryptoquery · string

Cryptocurrency code for which the price is returned per 1 unit.

currencyquery · stringrequired

Fiat currency code to return the price in.

Response will appear here

object

The usdt_transaction object

A USDT transaction monitoring request to track status changes and receive callbacks.

Attributes

txhashstringrequired

The transaction hash to monitor on the Ethereum blockchain.

cryptostringrequired

The cryptocurrency being monitored.

Allowed: USDT

match_callbackstringrequired

String to match part of your Store callback URL. Used when you have multiple stores to ensure the correct one is matched.

testnetintegerrequired

Indicates if the transaction is on the testnet. 0 = mainnet (Ethereum), 1 = sepolia testnet. Defaults to 0 if omitted.

Allowed: 01

Example object

{
  "txhash": "0x712f876339d877e7558f25b4c0b684c5e1d1a11472d407a175c231894b280714",
  "crypto": "USDT",
  "match_callback": "www.example.com",
  "testnet": 0
}
POST/monitor_txAuth required

Monitor USDT Transaction

Begin tracking a USDT transaction. Callbacks are sent to your store's endpoint whenever the transaction status changes.

Callback status values: -1 = Reverted, 0 = Unconfirmed, 1 = 1 confirmation, 2 = 2 confirmations (final — no callbacks sent beyond this).

Requires Bearer token authentication. Include Authorization: Bearer YOUR_API_KEY in the request header.

Request Body

txhashstringrequired

The transaction hash to monitor.

cryptostringrequired

The cryptocurrency used (USDT).

match_callbackstringrequired

String to match part of your store's callback URL. Used to identify the correct store when you have multiple.

testnetintegerrequired

Network. 0 = mainnet (Ethereum), 1 = Sepolia testnet.

Responses

txhashbody · stringrequired

The transaction hash to monitor.

cryptobody · stringrequired

The cryptocurrency used (USDT).

match_callbackbody · stringrequired

String to match part of your store's callback URL. Used to identify the correct store when you have multiple.

testnetbody · integerrequired

Network. `0` = mainnet (Ethereum), `1` = Sepolia testnet.

Response will appear here

object

The payment object

A confirmed payment received by one of your stores.

Attributes

idinteger

Internal payment ID.

timestampinteger

Unix timestamp when the payment was received.

cryptostring

Cryptocurrency used for the payment.

amountinteger

Payment amount in the smallest unit (satoshis for BTC).

addressstring

Receiving address.

txidstring

Transaction ID on the blockchain.

store_namestring

Name of the store that received the payment.

store_urlstring

Callback URL of the store.

fiat_valuenumber

Historical fiat value at time of payment (only present when the currency parameter is supplied).

Example object

{
  "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
}
GET/v2/paymentsAuth required

Get payment history

Returns confirmed payments received across all stores, ordered newest-first.

Requires Bearer token authentication. Include Authorization: Bearer YOUR_API_KEY in the request header.

Query Parameters

limitintegerdefault: 200

Maximum number of payments to return (1–200). Defaults to 200.

timeframestring enumdefault: "1M"

Time window to filter payments. 1W = 1 week, 2W = 2 weeks, 1M = 1 month, 3M = 3 months, 6M = 6 months, 1Y = 1 year.

"1W""2W""1M""3M""6M""1Y"
cryptostring enum

Filter by cryptocurrency. Omit to return all cryptocurrencies.

"BTC""BCH""USDT"
store_namestring

Partial case-insensitive store name filter.

currencystring

Fiat currency code (e.g. USD). When provided, each payment includes a fiat_value field with the historical fiat equivalent.

Responses

dataarray[]View payment object
limitquery · integer

Maximum number of payments to return (1–200). Defaults to 200.

timeframequery · string

Time window to filter payments. `1W` = 1 week, `2W` = 2 weeks, `1M` = 1 month, `3M` = 3 months, `6M` = 6 months, `1Y` = 1 year.

cryptoquery · string

Filter by cryptocurrency. Omit to return all cryptocurrencies.

store_namequery · string

Partial case-insensitive store name filter.

currencyquery · string

Fiat currency code (e.g. `USD`). When provided, each payment includes a `fiat_value` field with the historical fiat equivalent.

Response will appear here