API Documentation

Wallets & Stores

Wallets
V2 API

You can work with your wallets in Blockonomics with the Wallets API, including creating, retrieving, updating & deleting. In GET request, you can use balance=true to retrieve wallet balance as well.

You can expect a standardized wallet object working with wallet endpoints

  • id - Unique identified of the wallet
  • name - Given name
  • emailid - Email of the wallet owner
  • crypto - Cryptocurrency of the wallet
  • address - Address of the wallet
  • xpub_index - The current xpub index for BTC wallet
  • gap_limit - The gap limit for BTC wallet
  • created_at - Datetime of the wallet creation

If you have requested the wallet with balance, you can expect a balance object attached to the wallet object

  • confirmed_sats
  • unconfirmed_sats
  • confirmed_fiat
  • unconfirmed_fiat
  • fiat_currency
  • total_addresses
Definition

GET https://www.blockonomics.co/api/v2/wallets


POST https://www.blockonomics.co/api/v2/wallets

Request body: {"name":<Name of wallet for identification>,"address": <Xpub address>, "crypto":<type of crypto, only BTC accepted now>}


GET https://www.blockonomics.co/api/v2/wallets/{id}?balance=true


POST https://www.blockonomics.co/api/v2/wallets/{id}

Request body: { "name": <New name>, "gap_limit": <gap limit>}


DELETE https://www.blockonomics.co/api/v2/wallets/{id}


Example Request

curl -H 'Authorization: Bearer 2cDNOlCN985d7Rx3atSDOlmMeYaxzho2uPmHheIw4eU'

https://www.blockonomics.co/api/v2/wallets


curl -X POST -H 'Authorization: Bearer 2cDNOlCN985d7Rx3atSDOlmMeYaxzho2uPmHheIw4eU' -H "Content-Type: application/json" -d '{"name": "new wallet name", "gap_limit": 500}'

https://www.blockonomics.co/api/v2/wallets/88


curl -X DELETE -H 'Authorization: Bearer 2cDNOlCN985d7Rx3atSDOlmMeYaxzho2uPmHheIw4eU'

https://www.blockonomics.co/api/v2/wallets/88

Example Response

{ "data": [ { "id": 88, "name": "My Wallet", "emailid": "youremail@mail.com", "crypto": "BTC", "address": "vpub5ZChrqCCu9GuMccp7RsasDB9CcTrHqMGYJZ5WfHWquMtretu2p6QctKAAkyvStgxCMGVycC7Py7C9pz8UeLT9p85CHbacL3sEn3THtEit9t", "xpub_index": 1, "gap_limit": 20} ] }


{"data": { "id": 88, "name": "My Wallet", "emailid": "youremail@mail.com", "crypto": "BTC", "address": "vpub5ZChrqCCu9GuMccp7RsasDB9CcTrHqMGYJZ5WfHWquMtretu2p6QctKAAkyvStgxCMGVycC7Py7C9pz8UeLT9p85CHbacL3sEn3THtEit9t", "xpub_index": 1, "gap_limit": 20}}

Stores
V2 API

The Stores API lets you interact with all your stores, including creating, retrieving, updating & deleting, as well as attaching wallets to a store. You can use the parameter wallets=true with the Stores endpoint to retrieve the attached wallets of the stores.

You can expect a standardized store object working with store endpoints

  • id - Unique identified of the store
  • name - Given name
  • emailid - Email of the store owner
  • http_callback - Callback URL of the store

You can expect a list of wallet objects if you have made request to the stores with the wallets parameter.

Definition

GET https://www.blockonomics.co/api/v2/stores


POST https://www.blockonomics.co/api/v2/stores

Request body: {"name":<Name of store>,"http_callback": <URL of HTTP callback>}


GET https://www.blockonomics.co/api/v2/stores/{id}


POST https://www.blockonomics.co/api/v2/stores/{id}

Request body: {"name":<Name of store>,"http_callback": <URL of HTTP callback>}


DELETE https://www.blockonomics.co/api/v2/stores/{id}


GET https://www.blockonomics.co/api/v2/stores/{id}/wallets


Attach / Detach Wallets

POST https://www.blockonomics.co/api/v2/stores/{id}/wallets

Request body: { "wallet_id": <id of wallet to attach>}


DELETE https://www.blockonomics.co/api/v2/stores/{id}/wallets/{id}


Example Request

curl -H 'Authorization: Bearer 2cDNOlCN985d7Rx3atSDOlmMeYaxzho2uPmHheIw4eU'

https://www.blockonomics.co/api/v2/stores


curl -X POST -H 'Authorization: Bearer 2cDNOlCN985d7Rx3atSDOlmMeYaxzho2uPmHheIw4eU' -H "Content-Type: application/json" -d '{"name": "new store name", "http_callback": "https://newcallbackhost.com/callback"}'

https://www.blockonomics.co/api/v2/stores/88


curl -X DELETE -H 'Authorization: Bearer 2cDNOlCN985d7Rx3atSDOlmMeYaxzho2uPmHheIw4eU'

https://www.blockonomics.co/api/v2/stores/88

Example Response

{"data": [{"id": 88, "emailid": "youremail@mail.com", "name": "Store name", "http_callback": "https://www.yourhost.com/callback", "wallets": [{"id": 37, "name": "My Wallet", "emailid": "youremail@mail.com", "crypto": "BTC", "address": "vpub5ZChrqCCu9GuMccp7RsasDB9CcTrHqMGYJZ5WfHWquMtretu2p6QctKAAkyvStgxCMGVycC7Py7C9pz8UeLT9p85CHbacL3sEn3THtEit9t", "xpub_index": 1, "gap_limit": null}]}]}

Payments

Basic Info

Using payments API you can easily receive bitcoin payments on your custom website. Payments go directly to your bitcoin wallet. To get registered click on Get Started For Free on Merchants Page. Feel free to consult below resources:

Payments API Blog Tutorial Payments API Blog Tutorial Image
New Address

This will return a new address from your wallet to which the payer must send the payment. This call will increment index on server, so that each time you get a new address. To reset index you can use parameter reset=1. This will not increment index and will keep giving last generated address. It is useful for testing purposes.

If you have multiple xpubs under same emailid, you can choose the source Xpub (wallet) using the parameter match_callback. This will match given string within your stores and find attached Xpub (wallet)

Definition

POST https://www.blockonomics.co/api/new_address

POST https://www.blockonomics.co/api/new_address?reset=1

POST https://www.blockonomics.co/api/new_address?match_callback=www.example.com

Example Request

curl -d '' -H 'Authorization: Bearer 2cDNOlCN985d7Rx3atSDOlmMeYaxzho2uPmHheIw4eU'

https://www.blockonomics.co/api/new_address


curl -d '' -H 'Authorization: Bearer 2cDNOlCN985d7Rx3atSDOlmMeYaxzho2uPmHheIw4eU'

https://www.blockonomics.co/api/new_address?reset=1


curl -d '' -H 'Authorization: Bearer 2cDNOlCN985d7Rx3atSDOlmMeYaxzho2uPmHheIw4eU'

https://www.blockonomics.co/api/new_address?match_callback=www.example.com

Example Response

{"address": "14gaB2Xb7T1gGx65Sy2vdP37oU2TrJHWAA"}

{"address": "13C84DfUxXWsbi5haUc1uYacP9DmXg6bsc", "reset": 1}

{"address": "13C84DfUxXWsbi5haUc1uYacP9DmXg6bsc", "account": "xpub6D9qFCtaxyyP3aAMy..."}

Http Callback

Blockonomics will send http callback for payments on your address. For each callback following parameters are returned:

  • status is the status of transaction. 0-Unconfirmed, 1-Partially Confirmed, 2-Confirmed
  • addr is the receiving address
  • value is the recevied payment amount in satoshis
  • txid is the id of the paying transaction
  • For unconfirmed transactions an rbf attribute may be returned

A callback succeeds when the server returns 200 HTTP status. Callback are retried 7 times with an exponential backoff of 4 seconds. Use Merchant Wizard to configure callback for your server. Your callback url can also contain a secret paramater for additional security.

Warning about zero confirmations: It is always recommended to wait for atleast one confirmation to deliver your product/service. Sometimes you may want to accept zero confirmation for fast delivery of digital goods. In such cases you should reject unconfirmed payments that have rbf attribute. This is because RBF payments can be easily cancelled or reversed

Example Callback

/api/callback_url?status=0&addr=1C3FrYaGgUJ8R21jJcwzryQQUFCWFpwcrL&value=10000&txid=4cb3 0849ffcaf61c0e97e8351cca2a32722ceb6ad5f34e630b4acb7c6dc1e73b&rbf=1

Payment Notification

Use this to get realtime notification of payment on your bitcoin address (suitable for client side/browser notification). Parameters: addr is your bitcoin address. A websocket message is returned on successful payment containing the following fields:

  • status is the status of transaction. 0-Unconfirmed, 1-Partially Confirmed, 2-Confirmed
  • timestamp is the unix timestamp of transaction
  • value is the recevied payment amount in satoshis
  • txid is the id of the paying transaction
Definition

Websocket connection to wss://www.blockonomics.co/payment/<addr>

Example Request

var wsuri = "wss://www.blockonomics.co/payment/189CEMECgP36iXpCKQoBbRQn3dTCUPi5dm"

Example Response

{"status": 0, "timestamp": 1470371749, "value": 167377096, "txid": "aed36253434b90e45ded86ccf1729f5d2acd78bd7665c54e62d5000035a8f6d8"}

BTC Price

You can use this endpoint to fetch the current bitcoin to fiat price. Our prices are same as that of BitPay. We support all major fiat currencies. Here is the list of currency codes supported

Definition

GET https://www.blockonomics.co/api/price?currency=<currency_code>

Example Request

curl https://www.blockonomics.co/api/price?currency=EUR

Example Response

{"price": 7866.85}

Payment Buttons

Below are various API endpoints to get information about orders generated using payment buttons.To use any of these, you need to first create payment buttons at Merchants > Payment Buttons > Create. In the below requests you have to set apikey as the Authorization header of the request.

Get Order

Returns detail of payment button order. uuid is the unique identifier of the order.

GET /api/merchant_order/<uuid>

Get Order List

Returns list of all payment button orders in descending order of time. You can use limit to restrict the number of records (Default is 500).

GET /api/merchant_orders?limit=<number>

Order Hook

Each new/updated order will be notified using the order hook url. This url can be configured at Blockonomic's merchants page (Merchants->Payment Buttons->Options>Order Hook URL)

Example callback from server

<OrderHook_URL>?status=2&uuid=2b0c7e2cd523458098b2

Status Values:
  • -1 : PAYMENT_ERROR (Happens when Paid BTC amount is not matching expected value)
  • 0 : UNPAID
  • 1 : IN_PROCESS
  • 2 : PAID
Checkouts - Temp Products

Checkouts provide a dynamic way to collect charge from customers and add custom data to your products. This is achieved by creating temporary products via API which can be shown via payment button/link/widget. Few points about temp products:

  • Temp product by default inherits all fields from its parent product. You can create a parent product via Buttons
  • Temp products are automatically deleted after 7 days. Note that orders received via the temp product will still remain in the system
Definition

POST https://www.blockonomics.co/api/create_temp_product

Request body: {"parent_uid":<uid of parent product>,"product_name"(Optional): <name>, "product_description"(Optional):<description>, "value"(Optional):<price of product>, "extra_data"(Optional): <custom data>}

Headers: {Authorization: Bearer APIKey}

Example1 (Cart Checkout)

You have a custom website / e-commerce store. On checkout you want the customer to pay the cart value in bitcoin

curl -H 'Authorization: Bearer 2cDNOlCN985d7Rx3atSDOlmMeYaxzho2uPmHheIw4eU' -d'{"parent_uid": "b5c04c7c395011ea", "product_name": "Order #412", "product_description": "1 Red T-shirt\n2 Khaki Trousers", "value":500}'

https://www.blockonomics.co/api/create_temp_product

Example2 (Customized Product)

Create a customized product of the selected color/addons

curl -H 'Authorization: Bearer 2cDNOlCN985d7Rx3atSDOlmMeYaxzho2uPmHheIw4eU' -d'{"parent_uid": "b5c04c7c395011ea", "product_description":"Redmi 32GB (Yellow)": "value": 412}'

https://www.blockonomics.co/api/create_temp_product

Example3 (Attach custom data)

Attach customer userid/special notes to product

curl -H 'Authorization: Bearer 2cDNOlCN985d7Rx3atSDOlmMeYaxzho2uPmHheIw4eU' -d'{"parent_uid": "b5c04c7c395011ea", "extra_data":"user_id-19120"}'

https://www.blockonomics.co/api/create_temp_product

Displaying Checkout

API will return a temp product uid like this f7570454529a11e7-1ee5f340. You can set this uid to a payment button/link/widget

Payment Button

<a> href="" class="blockoPayBtn" data-toggle="modal" data-uid="f7570454529a11e7-1ee5f340"><img width=160 src="https://www.blockonomics.co/img/pay_with_bitcoin_medium.png"></a>

Payment Link

<a> href="" class="blockoPayBtn" data-toggle="modal" data-uid="f7570454529a11e7-1ee5f340"><img width=160 src="https://www.blockonomics.co/img/pay_with_bitcoin_medium.png"></a>

Payment Widget

<script src="https://blockonomics.co/js/pay_widget.js"></script><script> function pay() { Blockonomics.widget({ msg_area: 'payment_area', uid: 'f7570454529a11e7-1ee5f340', email: 'customer@email.com' }); }

Sending Bitcoin

We provide a self hosting free to use wallet service that you can deploy and use for sending bitcoin. Here are the details:

Test Payments

You can test payment integration without spending any bitcoins! By using Merchant > Logs, you can simulate test payments to your bitcoin address. These test payment notifications are send from our server (following API format), but not actually sent to the bitcoin network.

Dev Library

Tutorials, Videos, Code Projects and more

Explore