# Blockonomics API — Full Reference

> This document contains the complete Blockonomics API reference optimized for LLM consumption.
> Index-only version: https://developers.blockonomics.co/llms.txt
> Raw OpenAPI spec: https://developers.blockonomics.co/openapi.json

Base URL: https://www.blockonomics.co/api
Authentication: Bearer token — Authorization: Bearer YOUR_API_KEY
API keys: https://www.blockonomics.co/merchants#/api

---

## GET /balance
**Get confirmed and unconfirmed balance**

Returns confirmed and unconfirmed balance for one or more Bitcoin addresses or xpubs. All values are in satoshis.

Authentication: Bearer token required (Authorization: Bearer YOUR_API_KEY)

### Query Parameters
- `addr` — string (required): Whitespace-separated list of Bitcoin addresses and/or xpubs. A `+` or `%20` may also be used as a separator.

### Responses
- 200: Balance response.
  - `response` (array)
- 400: Invalid xPub(s) or address(es) provided
  - `status` (integer)
  - `error` (object)
- 401: This function requires you to login
  - `message` (string): Error message
- 404: No match found for one or more of the provided xPub(s) or address(es)
  - `status` (integer)
  - `error` (object)

Full reference: https://developers.blockonomics.co/docs/search/getbalance

---

## GET /searchhistory
**Get transaction history for wallet addresses**

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.

Authentication: Bearer token required (Authorization: Bearer YOUR_API_KEY)

### Query Parameters
- `addr` — string (required): Space-separated list of Bitcoin addresses and/or xpubs
- `fiat_currency` — 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" (optional): Fiat currency code. When provided, confirmed transactions include a `fiat_value_at_transaction_time` field with the historical fiat equivalent.

### Responses
- 200: Transaction history grouped by confirmation status
  - `pending` (array): Unconfirmed transactions (< 2 confirmations).
  - `history` (array): Confirmed transactions (2+ confirmations).
- 400: Bad request
  - `status` (integer)
  - `error` (object)

Full reference: https://developers.blockonomics.co/docs/search/gettransactionhistory

---

## GET /tx_detail
**Get transaction details**

Returns full details for a Bitcoin transaction including inputs, outputs, fee, size, and RBF status.

Authentication: Bearer token required (Authorization: Bearer YOUR_API_KEY)

### Query Parameters
- `txid` — string (required): Transaction ID

### Responses
- 200: Transaction details
  - `size` (integer): Transaction size in bytes
  - `time` (integer): Unix timestamp
  - `vin` (array): Transaction inputs
  - `vout` (array): Transaction outputs
  - `txid` (string): Transaction ID
  - `status` (string): Transaction status
  - `fee` (integer): Transaction fee in satoshis
  - `fee_usd` (number): Transaction fee in USD
  - `conf_time` (integer): Confirmation time in seconds
  - `rbf` (string): Replace-By-Fee status
  - `value` (integer): Transaction value in satoshis
  - `args_txin` (array): List of transaction input details
  - `args_txout` (array): List of transaction output details

Full reference: https://developers.blockonomics.co/docs/search/gettransactiondetails

---

## GET /op_return
**Search OP_RETURN data**

Search Bitcoin transactions by their OP_RETURN payload. Returns matching transactions with their transaction ID, timestamp, and embedded data.

### Query Parameters
- `q` — string (required): Search string to match against OP_RETURN data.
- `limit` — integer, default: 200 (optional): Maximum number of results to return.

### Responses
- 200: Matching transactions
  - `response` (array)
- 400: Invalid query (too short or limit out of range)
  - `message` (string)

Full reference: https://developers.blockonomics.co/docs/search/searchopreturn

---

## GET /v2/wallets
**List all wallets**

Returns a list of all wallets associated with your Blockonomics account.

Authentication: Bearer token required (Authorization: Bearer YOUR_API_KEY)

### Query Parameters
- `balance` — boolean, default: false (optional): Whether to include balance information

### Responses
- 200: List of wallets
  - `data` (array)

Full reference: https://developers.blockonomics.co/docs/wallets/get_v2-wallets

---

## POST /v2/wallets
**Add a wallet**

Attach a new wallet to your Blockonomics account.

Authentication: Bearer token required (Authorization: Bearer YOUR_API_KEY)

### Request Body (application/json)
- `name` — string (optional): Name your wallet for easier identification
- `address` — string (required): Wallet address. For BTC: xPub address. For USDT: EVM address (0x...).
- `crypto` — string, enum("BTC", "USDT") (required): Type of crypto. Supported values: BTC, USDT.

### Responses
- 200: Wallet created successfully
  - `data` (object)

Full reference: https://developers.blockonomics.co/docs/wallets/post_v2-wallets

---

## GET /v2/wallets/{id}
**Get wallet details**

Returns details of a specific wallet.

Authentication: Bearer token required (Authorization: Bearer YOUR_API_KEY)

### Path Parameters
- `id` — integer (required): The unique ID of the wallet

### Query Parameters
- `balance` — boolean, default: false (optional): Whether to include balance information

### Responses
- 200: Wallet details
  - `data` (object)

Full reference: https://developers.blockonomics.co/docs/wallets/get_v2-wallets-id

---

## POST /v2/wallets/{id}
**Update a wallet**

Update the details of a specific wallet.

Authentication: Bearer token required (Authorization: Bearer YOUR_API_KEY)

### Path Parameters
- `id` — integer (required): The unique ID of the wallet

### Request Body (application/json)
- `name` — string (optional): Give a new name to the wallet
- `gap_limit` — integer (optional): The number of unused addresses to check before considering the wallet as inactive. Do not touch this unless you know what you are doing.

### Responses
- 200: Wallet updated successfully
  - `data` (object)

Full reference: https://developers.blockonomics.co/docs/wallets/post_v2-wallets-id

---

## DELETE /v2/wallets/{id}
**Delete a wallet**

Remove a wallet from your Blockonomics account.

Authentication: Bearer token required (Authorization: Bearer YOUR_API_KEY)

### Path Parameters
- `id` — integer (required): The unique ID of the wallet

### Responses
- 200: Wallet deleted successfully

Full reference: https://developers.blockonomics.co/docs/wallets/delete_v2-wallets-id

---

## GET /v2/stores
**List all stores**

Returns a list of all stores associated with your Blockonomics account.

Authentication: Bearer token required (Authorization: Bearer YOUR_API_KEY)

### Query Parameters
- `wallets` — boolean, default: false (optional): Whether to include details of attached wallets

### Responses
- 200: List of stores
  - `data` (array)

Full reference: https://developers.blockonomics.co/docs/stores/get_v2-stores

---

## POST /v2/stores
**Create a new store**

Create a new store in your Blockonomics account.

Authentication: Bearer token required (Authorization: Bearer YOUR_API_KEY)

### Request Body (application/json)
- `name` — string (optional): Name of the store
- `http_callback` — string (required): Website's callback URL

### Responses
- 200: Store created successfully
  - `data` (object)

Full reference: https://developers.blockonomics.co/docs/stores/post_v2-stores

---

## GET /v2/stores/{id}
**Get store details**

Returns details of a specific store.

Authentication: Bearer token required (Authorization: Bearer YOUR_API_KEY)

### Path Parameters
- `id` — integer (required): The unique ID of the store

### Responses
- 200: Store details
  - `data` (object)

Full reference: https://developers.blockonomics.co/docs/stores/get_v2-stores-id

---

## POST /v2/stores/{id}
**Update a store**

Update the details of a specific store.

Authentication: Bearer token required (Authorization: Bearer YOUR_API_KEY)

### Path Parameters
- `id` — integer (required): The unique ID of the store

### Request Body (application/json)
- `name` — string (optional): New name for the store
- `http_callback` — string (optional): New callback URL for the store

### Responses
- 200: Store updated successfully
  - `data` (object)

Full reference: https://developers.blockonomics.co/docs/stores/post_v2-stores-id

---

## DELETE /v2/stores/{id}
**Delete store**

Delete a store from your Blockonomics account.

Authentication: Bearer token required (Authorization: Bearer YOUR_API_KEY)

### Path Parameters
- `id` — integer (required): The unique ID of the store

### Responses
- 200: Store deleted successfully

Full reference: https://developers.blockonomics.co/docs/stores/delete_v2-stores-id

---

## GET /v2/stores/{id}/wallets
**Get store wallets**

Returns a list of wallets attached to a specific store.

Authentication: Bearer token required (Authorization: Bearer YOUR_API_KEY)

### Path Parameters
- `id` — integer (required): The unique ID of the store

### Responses
- 200: List of store wallets
  - `data` (array)

Full reference: https://developers.blockonomics.co/docs/stores/get_v2-stores-id-wallets

---

## POST /v2/stores/{id}/wallets
**Attach wallet to store**

Attach an existing wallet in your Blockonomics account to a specific store.

Authentication: Bearer token required (Authorization: Bearer YOUR_API_KEY)

### Path Parameters
- `id` — integer (required): The unique ID of the store

### Request Body (application/json)
- `wallet_id` — integer (required): The unique ID of the wallet to attach

### Responses
- 200: Wallet attached successfully

Full reference: https://developers.blockonomics.co/docs/stores/post_v2-stores-id-wallets

---

## DELETE /v2/stores/{id}/wallets/{wallet_id}
**Detach wallet from store**

Detach a wallet from a specific store.

Authentication: Bearer token required (Authorization: Bearer YOUR_API_KEY)

### Path Parameters
- `id` — integer (required): The unique ID of the store
- `wallet_id` — integer (required): The unique ID of the wallet to detach

### Responses
- 200: Wallet detached successfully

Full reference: https://developers.blockonomics.co/docs/stores/delete_v2-stores-id-wallets-wallet-id

---

## POST /new_address
**Create or Get Payment Address**

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

Authentication: Bearer token required (Authorization: Bearer YOUR_API_KEY)

### Query Parameters
- `match_callback` — string (optional): 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.
- `crypto` — string, enum("BTC", "USDT"), default: "BTC" (optional): Cryptocurrency to use. When USDT, the same address is always returned.
- `reset` — integer, enum(0, 1), default: 0 (optional): Controls address generation for BTC. `0` (default) = new address, `1` = reuse last address. Ignored for USDT.

### Responses
- 200: Payment address generated successfully.
  - `address` (string): Generated payment address.
  - `crypto` (string): The cryptocurrency used for the address (BTC or USDT).
  - `reset` (integer): Indicates if the address index was reset (0 = new address, 1 = reuse last address).
  - `account` (string): The source xPub or wallet identifier.
- 400: Bad request
  - `error` (string): Error message describing what went wrong.
- 409: Conflict – Required wallet not attached to store
  - `status` (integer): HTTP status code
  - `error` (object)
- 422: Unsupported Cryptocurrency
  - `status` (integer): HTTP status code
  - `error` (object)

Full reference: https://developers.blockonomics.co/docs/merchants/post_new-address

---

## 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](https://www.blockonomics.co/api/currencies).

### Query Parameters
- `crypto` — string, enum("BTC", "USDT", "BCH", "ETH", "SOL", "XRP", "MATIC", "LTC"), default: "BTC" (optional): Cryptocurrency code for which the price is returned per 1 unit.
- `currency` — 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" (required): Fiat currency code to return the price in.

### Responses
- 200: Current price of 1 unit of the specified cryptocurrency in the specified fiat currency.
  - `price` (number): Current price of the cryptocurrency in the specified fiat currency.
- 400: Missing required parameter
  - `status` (integer): HTTP status code
  - `error` (object)
- 404: No price data available for the specified currency/crypto pair
  - `status` (integer): HTTP status code
  - `error` (object)
- 422: Unsupported fiat currency or crypto code provided
  - `status` (integer): HTTP status code
  - `error` (object)

Full reference: https://developers.blockonomics.co/docs/merchants/get_price

---

## GET /merchant_orders
**Get all orders**

Returns all payment button orders for your account.

Authentication: Bearer token required (Authorization: Bearer YOUR_API_KEY)

### Query Parameters
- `limit` — integer, default: 500 (optional): The number of records to return

### Responses
- 200: Order list response.
  - `response` (array)

Full reference: https://developers.blockonomics.co/docs/payment-buttons-and-checkouts/get_merchant-orders

---

## GET /merchant_order/{uuid}
**Get order details**

Returns details of a specific payment button order.

Authentication: Bearer token required (Authorization: Bearer YOUR_API_KEY)

### Path Parameters
- `uuid` — string (required): The unique identifier of the order

### Responses
- 200: Details of the payment button order
  - `code` (string): Product code
  - `xpub` (string): Extended public key of the wallet
  - `timestamp` (integer): Unix timestamp of the order
  - `currency` (string): Currency used to price the order
  - `name` (string): Name of the product
  - `status` (integer): Status of the order
  - `data` (object): Additional customer data
  - `emailid` (string): Merchant email ID
  - `order_id` (string): Unique identifier for the order
  - `address` (string): Bitcoin address for the payment
  - `value` (integer): Order value in fiat currency
  - `description` (string): Order description
  - `satoshi` (integer): Order value in satoshis
  - `txid` (string): Transaction ID if payment is made
  - `paid_satoshi` (integer): Amount paid in satoshis

Full reference: https://developers.blockonomics.co/docs/payment-buttons-and-checkouts/get_merchant-order-uuid

---

## POST /monitor_tx
**Monitor USDT Transaction**

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

Authentication: Bearer token required (Authorization: Bearer YOUR_API_KEY)

### Request Body (application/json)
- `txhash` — string (required): The transaction hash to monitor.
- `crypto` — string, enum("USDT") (required): The cryptocurrency used (USDT).
- `match_callback` — string (required): String to match part of your store's callback URL. Used to identify the correct store when you have multiple.
- `testnet` — integer, enum(0, 1), default: 0 (required): Network. `0` = mainnet (Ethereum), `1` = Sepolia testnet.

### Responses
- 200: Transaction successfully monitored.
  - `status` (integer): Current status of the transaction. `-1` = Reverted, `0` = Unconfirmed, `1` = 1 confirmation, `2` = 2 confirmations (final).

Full reference: https://developers.blockonomics.co/docs/merchants/post_monitor-tx

---

## GET /v2/payments
**Get payment history**

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

Authentication: Bearer token required (Authorization: Bearer YOUR_API_KEY)

### Query Parameters
- `limit` — integer, default: 200 (optional): Maximum number of payments to return (1–200). Defaults to 200.
- `timeframe` — string, enum("1W", "2W", "1M", "3M", "6M", "1Y"), default: "1M" (optional): Time window to filter payments. `1W` = 1 week, `2W` = 2 weeks, `1M` = 1 month, `3M` = 3 months, `6M` = 6 months, `1Y` = 1 year.
- `crypto` — string, enum("BTC", "BCH", "USDT") (optional): Filter by cryptocurrency. Omit to return all cryptocurrencies.
- `store_name` — string (optional): Partial case-insensitive store name filter.
- `currency` — string (optional): Fiat currency code (e.g. `USD`). When provided, each payment includes a `fiat_value` field with the historical fiat equivalent.

### Responses
- 200: List of payments
  - `data` (array)
- 400: Invalid parameter (limit out of range, unsupported crypto, or invalid timeframe)
- 401: Authentication required

Full reference: https://developers.blockonomics.co/docs/merchants/getpayments

---

## Guides

- [Getting Started](https://developers.blockonomics.co/docs/guides/getting-started): Create your Blockonomics account, connect a wallet, get your API key, and start accepting crypto payments.
- [Receiving Payments](https://developers.blockonomics.co/docs/guides/receiving-payments): Accept BTC and USDT payments on your website using the Blockonomics API — from checkout to confirmed callback.
- [Callbacks](https://developers.blockonomics.co/docs/guides/callbacks): Receive real-time payment notifications via HTTP callbacks when a payment status changes.
- [Testing](https://developers.blockonomics.co/docs/guides/testing): Simulate BTC and USDT payments without real funds using Blockonomics Test Mode.
- [Sending Bitcoin](https://developers.blockonomics.co/docs/guides/sending-bitcoin): Self-hosted wallet service for sending Bitcoin.
- [Web3 USDT Component](https://developers.blockonomics.co/docs/guides/web3-usdt-component): Embed a ready-made Web3 component that lets customers pay USDT from MetaMask or any browser wallet.
- [WebSocket Payment Notifications](https://developers.blockonomics.co/docs/guides/websocket-payment-notifications): Get real-time notifications when payments arrive at your Bitcoin addresses. No polling required.