When to use the API
Use the Blockonomics API if you are building a custom payment flow that isn’t covered by our plugins — for example, a mobile app, a custom e-commerce stack, or a SaaS platform.
If you’re using WordPress, WHMCS, or PrestaShop, use the plugin integrations instead — they handle all API calls for you.
Base URL
https://www.blockonomics.co/api
Quick reference
| Endpoint | Method | Description |
|---|
/new_address | GET | Generate a new Bitcoin address for payment |
/merchant/tx | GET | Check the status of a transaction |
/balance | POST | Check the balance of an xPub |
Getting your API key
- Log into your Blockonomics dashboard
- Go to Stores and copy the API key shown at the top
Keep your API key secret. Never expose it in client-side code or public repositories.
Authentication
Include your API key in the Authorization header on every request:
Authorization: Bearer YOUR_API_KEY
Generate a payment address
The core flow: when a customer is ready to pay, request a new address and display it to them.
GET https://www.blockonomics.co/api/new_address
Authorization: Bearer YOUR_API_KEY
{
"address": "1A1zP1eP5QGefi2DMPTfTL5SLmv7Divf2N",
"time": 1713183121
}
Receive payment callbacks
When a payment is made to an address you generated, Blockonomics sends a GET request to your store’s Callback URL with these parameters:
| Parameter | Description |
|---|
addr | The Bitcoin address that received payment |
status | 0 = unconfirmed, 1 = partially confirmed, 2 = fully confirmed |
value | Amount received in satoshis |
txid | The Bitcoin transaction ID |
GET https://yoursite.com/blockonomics-callback?addr=1A1zP1...&status=2&value=100000&txid=abc123
200 to acknowledge the callback. If it returns anything else, Blockonomics will retry.
Always verify the addr parameter matches an address you generated, and the value matches the expected payment amount before marking an order as paid.
Next steps
