BlockBee.io - Payment API Documentation (v1.5.8)

Download OpenAPI specification:Download



Documentation for BlockBee:
Before you start using our API, you will need an API key. To obtain one, register at BlockBee's Dashboard.

Receive a Payment

These endpoints simplify the process of generating unique payment addresses for each transaction, allowing you to track and manage payments more efficiently.

Create New Address

This method is used to generate a new address to give your clients, where they can send payments.

Please keep in mind that before making any transaction, you should check the minimum transfer limit for the specific cryptocurrency or token you want to use. If you transfer an amount that's less than the minimum limit set by BlockBee, your transaction will be rejected.

To save time and energy, it's recommended to check the pre-existing libraries for the features or functions you need before delving into the documentation.

Notice: The length of this request should not exceed 8192 characters.

Request
path Parameters
ticker
required
string

The ticker parameter in this API request refers to the unique identifier of the cryptocurrency to which you are making the request. It is included in the URL of the request and helps to specify the exact cryptocurrency that you want to retrieve data for. The ticker is typically a short code that uniquely identifies the cryptocurrency, or the token and it's network/blockchain.

For example, btc is the ticker for Bitcoin, and trc20/usdt is the ticker for USDT over TRC-20. Having this in mind, a request for USDT over TRC-20 will look like this: api.blockbee.io/trc20/usdt/create/.

Notes:

Example: btc
query Parameters
apikey
required
string

API Key provided by BlockBee's Dashboard.
Unsure how to get yours? Check this tutorial.
callback
required
string

The URL where the callbacks will be sent to. Must be a valid URL.

Notes:

  • The callback URL should be unique. The same callback URL will return the same address_in, meaning it works similarly to an ID. You can make your callback URL unique by adding GET parameters, like: ?user_id=1234. These will also be returned in the callbacks.
  • You may reuse callback URLs if for example you wish to create a deposit address_in. Note though that, once an address_in is created, if for any reason you wish to change the address, either in the parameter or at BlockBee's Dashboard, BlockBee systems will not change the address_out, meaning you will need to change your callback URL to generate a new address_in.
  • We advise you to URL Encode the callback URL, otherwise the GET parameters you add may be lost.
  • GET parameters you add to the callback URL will be sent as GET, even if you enable the post parameter.
  • It's advised to store the callback URL when making creating a new payment address if you wish to use the logs endpoint later.
  • For the complete documentation on callbacks, please refer to our callback documentation.
Example: callback=https://example.com?user_id=1124
address
string

By default, addresses are set in BlockBee's Dashboard, and to be able to set them in this parameter you need to enable the option "Address Override" when creating the API Key. If you wish to use the addresses set in the Dashboard, you can ignore this parameter and leave it empty.

The address parameter is where you specify where BlockBee will forward your payment. You can enter a single address or multiple addresses if you want to split the payment to multiple addresses.

If you're using multiple addresses, you will need to format them like this: percentage_1@address_1|percentage_2@address_2 and so on (you may add up to 20 addresses to split the payment). Percentages can range from 0.0001 (0.01%) to 1.0 (100%) and must add up to 1.00 (100%).

Addresses must be valid for the ticker you're using, otherwise the API will reject the payment. For example, if you try using a Bitcoin address while requesting a USDT TRC-20 address, API will throw an error.

Notes:

  • For multiple addresses, the minimum value per transaction (see cryptocurrencies page) is multiplied by the following formula: 1 + (N - 1) / 3, where N is the number of output addresses.
  • For more information about multi-address minimums, check our knowledge base.
Example: address=bc1qhfn0lw2kdu6umgf08x54y0ha7wclsj3g5sp6t3
pending
integer
Default: 0

Set to pending=1 to enable. If enabled you will be notified of pending transactions (transactions that were sent by the customer, but yet to be confirmed by the blockchain).

Notes:

  • To prevent repeated callbacks to your systems, the response to the callback request should be *ok* in plain text.
  • For a complete list of fields sent by our system, please refer to our pending callback documentation.
Example: pending=1
confirmations
integer
Default: 1

Number of blockchain confirmations you want before receiving the confirmed callback.
Min: 1
Example: confirmations=3
post
integer
Default: 0

Set this to post=1 to enable. If enabled callback will be sent as POST.

If disabled, will default to GET.

Notes:

  • GET parameters you added to the callback URL will still be sent as GET.
Example: post=1
json
integer
Default: 0

Set this to json=1 to enable. If enabled the callback body will be sent as JSON.

If disabled, will default to GET.

Notes:

  • GET parameters you added to the callback URL will still be sent as GET.
Example: json=1
priority
string
Default: "default"

Allows you to set the priority with which funds should be forwarded to the provided address. It reflects the amount of fees paid to the blockchain network and can affect the speed of transaction confirmation.

Notes:

  • Only supported when using Bitcoin, Ethereum/ERC-20 and Litecoin. Priorities are different per each supported blockchain.
  • You can find the priorities to use with this endpoint, per blockchain, in our knowledge base.
Example: priority=fast
multi_token
integer
Default: 0

Allows customers to pay with any token supported by BlockBee API, even if the token is different from what the user initially specified.

However, you should ensure that your Wallet supports the tokens you expect customers to pay with and that your system can handle price conversions. For example, if a customer wishes to receive 1000 USDT (or equivalent) and a client sends 1000 TRX, the system should be able to handle that scenario.

Notes:

  • Make sure the wallet you're using supports all the tokens supported by BlockBee before enabling this parameter.
  • If you are using your favorite exchange's deposit address to receive the funds, it's advised to leave this parameter disabled, since sometimes the deposit addresses may differ between blockchains and tokens.
  • Disabled by default, use multi_token=1 to enable it.
  • Available only for TRC20 and all supported EVM-based blockchains (eg. ERC20, BEP20, POLYGON).
  • If disabled and the customer send a different token from the initially specified, BlockBee API will ignore these funds.
  • If enabled on unsupported blockchains, API won't throw an error. Instead it just ignores it.
  • For more information about this parameter, check our knowledge base.
Example: multi_token=1
convert
integer
Default: 0

If enabled, returns the converted value converted to FIAT in the callback, with the parameters value_coin_convert and value_forwared_coin_convert.

Notes:

  • Disabled by default, use convert=1 to enable it.
  • The value of the fields are json-encoded.
Example: convert=1
Responses
200

Address was created.

Response Schema: application/json
address_in
string

Address generated by our API. You must provide it to your customer in order to receive payments.
address_out
string

Your address(es), where the payment will be forwarded to, should be the same address(es) you provided.
callback_url
string

The callback URL you provided.
priority
string

The confirmation priority you requested.
status
string

Status of the request. Should be `success` if the request didn't fail.
400

Error creating address.

get/{ticker}/create/
Request samples
Response samples
application/json
{
  • "address_in": "14PqCsA7KMgseZMPwg6mJy754MtQkrgszu",
  • "address_out": "1H6ZZpRmMnrw8ytepV3BYwMjYYnEkWDqVP (single address)\n\n{1H6ZZpRmMnrw8ytepV3BYwMjYYnEkWDqVP: 0.70, 1PE5U4temq1rFzseHHGE2L8smwHCyRbkx3: 0.30} (multiple addresses)\n",
  • "priority": "default",
  • "status": "success"
}

Check Payment Logs


This method provides information and callbacks for addresses created through the create endpoint.

It returns a list of callbacks made at the specified callbacks parameter, and allows to track payment activity and troubleshoot any issues.

Request
path Parameters
ticker
required
string

The ticker parameter in this API request refers to the unique identifier of the cryptocurrency to which you are making the request. It is included in the URL of the request and helps to specify the exact cryptocurrency that you want to retrieve data for. The ticker is typically a short code that uniquely identifies the cryptocurrency, or the token and it's network/blockchain.

For example, btc is the ticker for Bitcoin, and trc20/usdt is the ticker for USDT over TRC-20. Having this in mind, a request for USDT over TRC-20 will look like this: api.blockbee.io/trc20/usdt/create/.

Notes:

Example: btc
query Parameters
apikey
required
string

API Key provided by BlockBee's Dashboard.
Unsure how to get yours? Check this tutorial.
callback
required
string

The URL of the callback. Must be the same URL provided when the payment was created.

Notes:

  • It's advised to store the callback URL when creating a new payment address if you wish to use this endpoint later.
  • We advise URL Encoding the callback when making the request. If using one of our libraries there's no need for it.
Example: callback=https://example.com?user_id=1124
Responses
200

List of payments sent to this callback.

Response Schema: application/json
address_in
string

Generated address for the callback URL provided.
address_out
string

Your address(es), where the payment will be forwarded to, should be the same address(es) you provided.

Notes:

  • Response will be {1H6ZZpRmMnrw8ytepV3BYwMjYYnEkWDqVP: 0.70, 1PE5U4temq1rFzseHHGE2L8smwHCyRbkx3: 0.30} (multiple addresses)
callback_url
string

The callback URL you provided.
status
string

Status of the request. Should be `success` if the request didn't fail.
notify_pending
boolean

Shows if you enabled the pending callback when creating the address.
notify_confirmations
integer

Number of confirmations required before sending the confirmed callback.
priority
string

The confirmation priority you requested.
Array of objects (log_items)

List of payments made to this address, together with the logs of the callbacks to your system.
400

Your request couldn't be processed, please try again later.

404

No request or no payment callbacks found.

get/{ticker}/logs/
Request samples
Response samples
application/json
{}

Utils

Create custom and specially tailored UIs for your business with the help of these endpoints.
These endpoints provide you with essential features to make conversions, get estimates, retrieve information, and generate QR codes.

Service Information

Endpoint that provides information regarding BlockBee API Service (e.g supported blockchains, cryptocurrencies and tokens).

Request
query Parameters
prices
integer
Default: 0

If you want to receive also the coin prices, set to 1 to enable the prices.
Example: prices=1
Responses
200

Info fetched successfully.

Response Schema: application/json
object
object
get/info/
Request samples
Response samples
application/json
{
  • "btc": {
    },
  • "trc20": {
    }
}

Check Coin Information

Use this endpoint to retrieve information about the cryptocurrency you intend to use. This endpoint provides detailed information about the cryptocurrency/token provided in the ticker parameter.

Request
path Parameters
ticker
required
string

The ticker parameter in this API request refers to the unique identifier of the cryptocurrency to which you are making the request. It is included in the URL of the request and helps to specify the exact cryptocurrency that you want to retrieve data for. The ticker is typically a short code that uniquely identifies the cryptocurrency, or the token and it's network/blockchain.

For example, btc is the ticker for Bitcoin, and trc20/usdt is the ticker for USDT over TRC-20. Having this in mind, a request for USDT over TRC-20 will look like this: api.blockbee.io/trc20/usdt/create/.

Notes:

Example: btc
query Parameters
apikey
required
string

API Key provided by BlockBee's Dashboard.
Unsure how to get yours? Check this tutorial.
prices
integer
Default: 1

If you want to receive also the coin prices, set to 1 to enable the prices.
Responses
200

Info fetched successfully.

Response Schema: application/json
status
string

Status of the request. Should be `success` if the request didn't fail.
coin
string

Human readable name of the currency.
ticker
string

Ticker of the currency.
minimum_transaction_coin
string

Minimum transaction value for this currency, values below this value are disregarded by BlockBee API.
minimum_fee_coin
string

BlockBee currently doesn't charge a minimum fee.
On Bitcoin and Bitcoin Cash there's a minimum transaction fee of 546 Satoshis due to dust threshold. For Litecoin it's 5460 Litoshis.
fee_percent
number

Fee percentage for this currency.
network_fee_estimation
string

Estimation of the blockchain fee for this cryptocurrency/token. **Notes:** * This value is informative. To obtain a blockchain fee estimation use the estimate endpoint instead.
prices
object

Object with the exchange rate of this currency in various FIAT currencies.

Keys are the names of the currencies, values are the exchange rates.

Updated every 5 minutes.

prices_updated
string

Datetime of the last price update.
400

Error fetching info.

get/{ticker}/info/
Request samples
Response samples
application/json
{
  • "status": "success",
  • "coin": "Bitcoin",
  • "ticker": "btc",
  • "minimum_transaction_coin": "0.00008000",
  • "minimum_fee_coin": "0.00000546",
  • "fee_percent": "1.00",
  • "network_fee_estimation": "0.006548837643539048",
  • "prices": "{'DKK': '56281.94', 'CAD': '10985.14', 'AED': '30517.01', 'BRL': '34243.36', 'USD': '8308.47', 'MXN': '160193.26', 'CNY': '58740.88', 'INR': '591471.72', 'JPY': '899719.16', 'HKD': '65173.93', 'GBP': '6616.08', 'EUR': '7535.35'}",
  • "prices_updated": "2019-10-14T13:00:09.585Z"
}

Generate QR Code

This method generates a base64-encoded QR Code image for payments.

Request
path Parameters
ticker
required
string

The ticker parameter in this API request refers to the unique identifier of the cryptocurrency to which you are making the request. It is included in the URL of the request and helps to specify the exact cryptocurrency that you want to retrieve data for. The ticker is typically a short code that uniquely identifies the cryptocurrency, or the token and it's network/blockchain.

For example, btc is the ticker for Bitcoin, and trc20/usdt is the ticker for USDT over TRC-20. Having this in mind, a request for USDT over TRC-20 will look like this: api.blockbee.io/trc20/usdt/create/.

Notes:

Example: btc
query Parameters
apikey
required
string

API Key provided by BlockBee's Dashboard.
Unsure how to get yours? Check this tutorial.
address
required
string

The payment address (address_in from our system).
value
integer

Value to request the user. Optional.

Notes:

  • If left empty the QR Code will only contain the address.
  • It is important to mention that the value parameter might not be compatible with many exchanges and wallets. While it works with Trust and Exodus wallets, some user wallets or exchanges may only read the address and ignore the value field (inserting both the address and the value in the address field). Hence, it is advised to use the value field cautiously and be aware that it may not be recognized by all wallets and exchanges, causing some confusion to the customer.
size
integer
Default: 512

Size of the QR Code image in pixels.
Min: 64
Max: 1024
Example: size=300
Responses
200

The QR Code.

Response Schema: application/json
status
string

Status of the request. Should be success if the request didn't fail.
qr_code
string

Base64-encoded image of the QR Code.

Here is an example of how to use this:

<img src="data:image/png;base64,{qr_code}" alt="Payment QR Code"/>

You may use it in every situation where is supported, just don't forget to add data:image/png;base64, before the qr_code.

payment_uri
string

Payment URI useful if you want to make a clickable button.
get/{ticker}/qrcode/
Request samples
Response samples
application/json
{
  • "status": "success",
  • "qr_code": "...",
  • "payment_uri": "..."
}

Estimate Blockchain Fees


This method allows you to estimate blockchain fees to forward a transaction to your wallet address.

Notes:

  • This is an estimation only, and might change significantly when the transaction is processed by the blockchain. BlockBee is not responsible if blockchain fees differ from this estimation when forwarding the funds.
  • Does not include BlockBee's fees.
Request
path Parameters
ticker
required
string

The ticker parameter in this API request refers to the unique identifier of the cryptocurrency to which you are making the request. It is included in the URL of the request and helps to specify the exact cryptocurrency that you want to retrieve data for. The ticker is typically a short code that uniquely identifies the cryptocurrency, or the token and it's network/blockchain.

For example, btc is the ticker for Bitcoin, and trc20/usdt is the ticker for USDT over TRC-20. Having this in mind, a request for USDT over TRC-20 will look like this: api.blockbee.io/trc20/usdt/create/.

Notes:

Example: btc
query Parameters
apikey
required
string

API Key provided by BlockBee's Dashboard.
Unsure how to get yours? Check this tutorial.
addresses
integer
Default: 1

The number of addresses to forward the funds to. Should be the same you set in the BlockBee's Dashboard or in the address parameter.

Notes:

  • The higher the number of addresses, the higher the blockchain fee will be.
Example: addresses=3
priority
string
Default: "default"

This parameter allows you to set the priority with which funds should be forwarded to the provided address. It reflects the amount of fees paid to the blockchain network and can affect the speed of transaction confirmation. It's different per currency/network.

Notes:

  • You can find the priorities to use with this endpoint, per blockchain, in our knowledge base.
  • Only supported when using Bitcoin, Ethereum/ERC-20 and Litecoin.
Example: priority=fast
Responses
200

Estimated cost.

Response Schema: application/json
status
string

Status of the request. Should be `success` if the request didn't fail.
estimated_cost
integer

Estimated cost in the coin.
estimated_cost_currency
object

Object with the estimated cost in various FIAT currencies.

Keys are the names of the currencies, values are the estimated costs.

400

Your request couldn't be processed, please try again later

get/{ticker}/estimate/
Request samples
Response samples
application/json
{
  • "status": "success",
  • "estimated_cost": "0.00001",
  • "estimated_cost_currency": "{'USD': '0.09', 'EUR': '0.08', 'GBP': '0.07', 'CAD': '0.11', 'JPY': '10.21', 'AED': '0.33', 'DKK': '0.58', 'BRL': '0.46', 'CNY': '0.56', 'HKD': '0.69', 'INR': '6.67', 'MXN': '1.81', 'UGX': '310.74', 'PLN': '0.35', 'PHP': '4.56', 'CZK': '1.91', 'HUF': '27.95', 'BGN': '0.15', 'RON': '0.39', 'LKR': '18.02'}"
}

Convert Prices

With this method, you can effortlessly convert prices between FIATs and cryptocurrencies, or even between different cryptocurrencies.

Note:

  • Prices are fetched every 5 minutes from CoinMarketCap.
Request
path Parameters
ticker
required
string

The ticker parameter in this API request refers to the unique identifier of the cryptocurrency to which you are making the request. It is included in the URL of the request and helps to specify the exact cryptocurrency that you want to retrieve data for. The ticker is typically a short code that uniquely identifies the cryptocurrency, or the token and it's network/blockchain.

For example, btc is the ticker for Bitcoin, and trc20/usdt is the ticker for USDT over TRC-20. Having this in mind, a request for USDT over TRC-20 will look like this: api.blockbee.io/trc20/usdt/create/.

Notes:

Example: btc
query Parameters
apikey
required
string

API Key provided by BlockBee's Dashboard.
Unsure how to get yours? Check this tutorial.
value
required
number

Value you wish to convert in the cryptocurrency/token of the ticker you are using.
Example: value=10
from
required
string

Specify the currency you wish to convert from, whether it is FIAT or cryptocurrency.

Check our full list of supported cryptocurrencies.

FIAT currencies supported in this list are (if the FIAT currency you wish to use is not in this list, you may contact us in order to add it to our service):

  • (USD) United States Dollar
  • (EUR) Euro
  • (GBP) Great Britain Pound
  • (CAD) Canadian Dollar
  • (JPY) Japanese Yen
  • (AED) UAE Dollar
  • (MYR) Malaysian Ringgit
  • (IDR) Indonesian Rupiah
  • (THB) Thai Baht
  • (CHF) Swiss Franc
  • (SGD) Singapore Dollar
  • (RUB) Russian Ruble
  • (ZAR) South African Rand
  • (TRY) Turkish Lira
  • (LKR) Sri Lankan Rupee
  • (RON) Romanian Leu
  • (BGN) Bulgarian Lev
  • (HUF) Hungarian Forint
  • (CZK) Czech Koruna
  • (PHP) Philippine Peso
  • (PLN) Poland Zloti
  • (UGX) Uganda Shillings
  • (MXN) Mexican Peso
  • (INR) Indian Rupee
  • (HKD) Hong Kong Dollar
  • (CNY) Chinese Yuan
  • (BRL) Brazilian Real
  • (DKK) Danish Krone
  • (TWD) New Taiwan Dollar
  • (AUD) Australian Dollar
  • (NGN) Nigerian Naira
  • (SEK) Swedish Krona
  • (NOK) Norwegian Krone
Example: from=usd
Responses
200

The converted value.

Response Schema: application/json
value_coin
number

Converted value for the selected currencies.

exchange_rate
number

The exchange rate between the 2 currencies.

status
string

Status of the request. Should be success if the request didn't fail.

400

Your request couldn't be processed, please try again later.

get/{ticker}/convert/
Request samples
Response samples
application/json
{
  • "value_coin": "0.01",
  • "exchange_rate": "47000",
  • "status": "success"
}

Callbacks

These callbacks are dispatched by our API to your platform when a user sends a payment to the address generated by our system. Your platform should be able to handle these callbacks, which are requests made to the URL provided in the callback parameter.

Each callback is sent with an additional header, x-ca-signature. This is a base64-encoded 1024-bit RSA-SHA256 signature of the callback. The specific data signed depends on the type of callback you're receiving. For callbacks sent via GET, the entire request URL to your system (including all GET parameters) is signed. If the callback is sent via POST, then the entire body of the request is signed. The Public Key for verification can be retrieved from this this endpoint.

Check our knowledge base to learn how to verify the callback with code samples.

BlockBee API will stop sending callbacks under one of these two circumstances:

  • Your system responds with an *ok* message or an HTTP 200 status code, indicating that the callback has been successfully received and processed.
  • In case your system fails to response successfully to the callback, BlockBee API will retry sending the callback in a specific timing. Regarding the timing of these callbacks, we employ an exponential backoff strategy. Initially, the system waits for 6 minutes before making the first retry attempt. With each subsequent attempt, this wait time doubles, hence increasing the time between attempts in an exponential manner until the transaction is older than 3 days.

Callbacks are sent everytime funds are received in a generated address. If you're having issues receiving our callbacks it might be due to these factors:

  • You sent the wrong token to the address, for example, created a USDt transaction and sent TRX to the address, leading to our system ignoring the transaction.
  • The callback URL you provided in the callback parameter is not reachable online.
  • You might have some security system in place (e.g Cloudflare protection) that's preventing our callbacks reaching your platform.

Note: We advise whitelisting our server IPs in order to avoid issues with the callbacks: 145.239.119.223 and 135.125.112.47

Pending CallbackWebhook

Callback issued when a client's transaction is pending confirmation.

Notes:

  • Only issued if you have requested to be notified of pending transactions. Only sent when post parameter is set to 1, when creating a new address.
  • Sent via POST if post=1 parameter set, else sent via GET.
Request
query Parameters
uuid
string

This is an unique identifier to each payment your clients have made, so you can easily track any duplicate callbacks sent, in the case our system doesn't mark the callback as successful.
Example: uuid=dbfcb40e-5a6b-4305-9fa2-b0fbda6e3ff2
address_in
string

Address generated by BlockBee, where your customer sent the payment.
Example: address_in=3PFoGK63cVVUWnd2vu7W1kM83NXUfvzMqM
address_out
string

Address(es) where BlockBee forwarded the payment.
Example: address_out=1H6ZZpRmMnrw8ytepV3BYwMjYYnEkWDqVP (single address)<br/> {1H6ZZpRmMnrw8ytepV3BYwMjYYnEkWDqVP: 0.70, 1PE5U4temq1rFzseHHGE2L8smwHCyRbkx3: 0.30} (multiple addresses)
txid_in
string

Transaction hash of your customer's payment.
Example: txid_in=a2174ffd39289100709f2a07b129cdbba69df2e22e5be1830221dab1fd4e332c
confirmations
integer

Number of confirmations of the current transaction.
Example: confirmations=1
value_coin
number

This is the payment amount sent by your customer before any fees are deducted.

Notes:

Example: value_coin=0.05
value_coin_convert
string

Converted value to various FIAT currencies of the value_coin.

Notes:

  • This parameter will only be shown if added the convert=1 parameter in the /create/ endpoint.
  • Response is json-encoded.
Example: value_coin_convert={"USD": "3.20", "EUR": "3.05", "GBP": "2.62", "CAD": "4.16", "JPY": "431.90", "AED": "11.77", "DKK": "22.67", "BRL": "16.52", "CNY": "21.43", "HKD": "25.16", "INR": "249.97", "MXN": "64.95", "UGX": "11975.46", "PLN": "14.25", "PHP": "173.14", "CZK": "75.37", "HUF": "1220.10", "BGN": "5.94", "RON": "15.02", "LKR": "1153.30", "TRY": "55.54", "ZAR": "51.36", "RUB": "181.24"}
coin
string

Ticker of the coin used for the payment: ['btc', 'bch', 'ltc'', 'eth', 'trx']

For ERC-20 (ETH) Tokens, this parameter will be erc20_ + the ticker of the token, e.g erc20_usdt

For TRC-20 (Tron) Tokens, this parameter will be trc20_ + the ticker of the token, e.g trc20_usdt

For BEP-20 (BSC) Tokens, this parameter will be bep20_ + the ticker of the token, e.g bep20_usdt

For Polygon Tokens, this parameter will be polygon_ + the ticker of the token, e.g polygon_usdt

Example: coin=btc
price
number

Coin price in USD at the time of the callback.
Example: price=55.59
pending
integer

Being the pending callback, this value should be 1.
Example: pending=1
Responses
200

Expected response from your server.

Response Schema: text/plain
string
Response samples
text/plain
*ok*

Confirmed CallbackWebhook

Callback issued when a client's transaction has been confirmed by the network.

Request
query Parameters
uuid
string

This is an unique identifier to each payment your clients have made, so you can easily track any duplicate callbacks sent, in the case our system doesn't mark the callback as successful.
Example: uuid=dbfcb40e-5a6b-4305-9fa2-b0fbda6e3ff2
address_in
string

Address generated by BlockBee, where your customer sent the payment.
Example: address_in=3PFoGK63cVVUWnd2vu7W1kM83NXUfvzMqM
address_out
string

Address(es) where BlockBee forwarded the payment.
Example: address_out=1H6ZZpRmMnrw8ytepV3BYwMjYYnEkWDqVP (single address)<br/> {1H6ZZpRmMnrw8ytepV3BYwMjYYnEkWDqVP: 0.70, 1PE5U4temq1rFzseHHGE2L8smwHCyRbkx3: 0.30} (multiple addresses)
txid_in
string

Transaction hash of your customer's payment.
Example: txid_in=a2174ffd39289100709f2a07b129cdbba69df2e22e5be1830221dab1fd4e332c
txid_out
string

Transaction hash of the payment forwarded to your address(es) by BlockBee.
Example: txid_out=a2174ffd39289100709f2a07b129cdbba69df2e22e5be1830221dab1fd4e332c
confirmations
integer

Number of blockchain confirmations of the current transaction.

Notes:

  • This parameter will only appear in the confirmed callback.
Example: confirmations=1
value_coin
number

This is the payment amount sent by your customer before any fees are deducted.

Notes:

Example: value_coin=0.05
value_coin_convert
string

Converted value to various FIAT currencies of the value_coin.

Notes:

  • This parameter will only be shown if added the convert=1 parameter in the /create/ endpoint.
  • Response is json-encoded.
Example: value_coin_convert={"USD": "3.20", "EUR": "3.05", "GBP": "2.62", "CAD": "4.16", "JPY": "431.90", "AED": "11.77", "DKK": "22.67", "BRL": "16.52", "CNY": "21.43", "HKD": "25.16", "INR": "249.97", "MXN": "64.95", "UGX": "11975.46", "PLN": "14.25", "PHP": "173.14", "CZK": "75.37", "HUF": "1220.10", "BGN": "5.94", "RON": "15.02", "LKR": "1153.30", "TRY": "55.54", "ZAR": "51.36", "RUB": "181.24"}
value_forwarded_coin
number

Value forwarded to you, after fees deducted.
Example: value_forwarded_coin=0.05
value_forwarded_coin_convert
string

Converted value to various FIAT currencies of the value_forwarded_coin.

Notes:

  • This parameter will only be shown if added the convert=1 parameter in the /create/ endpoint.
  • Response is json-encoded.
Example: value_forwarded_coin_convert={"USD": "3.17", "EUR": "3.01", "GBP": "2.59", "CAD": "4.12", "JPY": "427.16", "AED": "11.64", "DKK": "22.41", "BRL": "16.33", "CNY": "21.20", "HKD": "24.88", "INR": "247.19", "MXN": "64.25", "UGX": "11855.29", "PLN": "14.08", "PHP": "171.25", "CZK": "74.50", "HUF": "1206.19", "BGN": "5.88", "RON": "14.86", "LKR": "1140.51", "TRY": "54.93", "ZAR": "50.82", "RUB": "179.22"}
fee_coin
number

Fee paid to BlockBee, deducted from value_coin amount.
Example: fee_coin=0.02
coin
string

Ticker of the coin used for the payment: ['btc', 'bch', 'ltc'', 'eth', 'trx']

For ERC-20 (ETH) Tokens, this parameter will be erc20_ + the ticker of the token, e.g erc20_usdt

For TRC-20 (Tron) Tokens, this parameter will be trc20_ + the ticker of the token, e.g trc20_usdt

For BEP-20 (BSC) Tokens, this parameter will be bep20_ + the ticker of the token, e.g bep20_usdt

For Polygon Tokens, this parameter will be polygon_ + the ticker of the token, e.g polygon_usdt

Example: coin=btc
price
number

Coin price in USD at the time of the callback.
Example: price=55.59
pending
integer

Being the confirmed callback, this value should be 0.

Payment was confirmed by the blockchain.

Example: pending=0
Responses
200

Expected response from your server.

The callback will be marked as successful when it receives the following response from your server.

Response Schema: text/plain
string
Response samples
text/plain
*ok*

Checkout - Payments

Documentation on how to use our ready-made Checkout page to receive cryptocurrency payments.

Check the demo!

Before using the Checkout page (Failing to do so will lead to errors when requesting a Payment link):

Create a Checkout Payment

This method allows you to request a new Payment link.

Request
query Parameters
apikey
required
string

API Key provided by BlockBee's Dashboard.
Unsure how to get yours? Check this tutorial.
redirect_url
required
string

URL where your customers will be redirected to after successfully completing the payment.

The success_token token will be added as GET parameter to this URL, together with any GET parameter you might have provided in your redirect_url, which can be used to validate the payment.

Notes:

  • Even though it's possible to use this page to validate the payment, we recommend using the notify_url
Example: redirect_url=https://example.com/success/?order_id=12345
value
required
number

Value of the order in the FIAT currency set in your Payment Settings at BlockBee's Dashboard.
Example: value=10
currency
string

Set the FIAT currency used in the value parameter.

Note: Will override the FIAT currency set in your Payment Settings at BlockBee's Dashboard.

FIAT currencies supported in this list are (if the FIAT currency you wish to use is not in this list, you may contact us in order to add it to our service):

  • (USD) United States Dollar
  • (EUR) Euro
  • (GBP) Great Britain Pound
  • (CAD) Canadian Dollar
  • (JPY) Japanese Yen
  • (AED) UAE Dollar
  • (MYR) Malaysian Ringgit
  • (IDR) Indonesian Rupiah
  • (THB) Thai Baht
  • (CHF) Swiss Franc
  • (SGD) Singapore Dollar
  • (RUB) Russian Ruble
  • (ZAR) South African Rand
  • (TRY) Turkish Lira
  • (LKR) Sri Lankan Rupee
  • (RON) Romanian Leu
  • (BGN) Bulgarian Lev
  • (HUF) Hungarian Forint
  • (CZK) Czech Koruna
  • (PHP) Philippine Peso
  • (PLN) Poland Zloti
  • (UGX) Uganda Shillings
  • (MXN) Mexican Peso
  • (INR) Indian Rupee
  • (HKD) Hong Kong Dollar
  • (CNY) Chinese Yuan
  • (BRL) Brazilian Real
  • (DKK) Danish Krone
  • (TWD) New Taiwan Dollar
  • (AUD) Australian Dollar
  • (NGN) Nigerian Naira
  • (SEK) Swedish Krona
  • (NOK) Norwegian Krone

Some cryptocurrencies are also accepted in this field (for the conversion of the value):

  • (BTC) Bitcoin
  • (ETH) Ethereum
  • (USDT) Tether USDt
  • (USDC) USD Coin
Example: currency=eur
item_description
string

Description of the product or service being paid. This information will appear on the Checkout page.
Example: item_description=Description of the product you are selling
expire_at
number

Epoch time in seconds at which the Checkout payment will expire.

Notes:

  • Minimum is 1h.
  • If not set, the Payment link will never expire.
  • Timestamp must be in seconds
Example: expire_at=1673438907
notify_url
string

URL where our system will send a payment notification (IPN), when a deposit is made.

Notes:

  • We advise you to URL Encode the notify URL, otherwise the GET parameters you add may be lost.
  • GET parameters you add to the notify URL will be sent as GET, even if you enable the post parameter.
  • For a complete list of fields sent by our system, please refer to our IPN for Deposits documentation.
  • To prevent repeated IPNs to your systems, the response to the IPN request should be *ok* in plain text.
post
number
Default: 0

Set this to 1 if you wish to receive the IPN as a POST request.

If set to 0, API will default to GET.

Notes:

  • GET parameters you added to the notify_url URL will still be sent as GET.
Example: post=1
Responses
200

Payment URL was created successfully.

Response Schema: application/json
status
string

Status of the request. Should be success if the request didn't fail.
success_token
string

Security token only known by your system and BlockBee so you can make sure the order was actually paid by your customer.
payment_url
string

Payment URL where your customer should be redirected to initiate the transaction.

Note: It's possible to pre-select a cryptocurrency for the checkout page by using the coin GET parameter.
* All of our supported tickers can be found at our cryptocurrencies page. Please replace the / with a _.
* Example: In order to pre-select Bitcoin for the payment, append ?coin=trc20_usdt to the payment_url as the following example: https://pay.blockbee.io/payment/fG78jtx96ugjtu0eIbeLmFB9z0feJf9N?coin=trc20_usdt.
400

Your request couldn't be processed, please try again later

get/checkout/request/
Request samples
Response samples
application/json
{}

Retrieve Payment Logs

This method allows you to check the payment status and the IPN logs for a payment using our API.

Request
query Parameters
apikey
required
string

API Key provided by BlockBee's Dashboard.
Unsure how to get yours? Check this tutorial.
token
required
string

Payment Token provided upon requesting the payment.

Example: token=fG78jtx96ugjtu0eIbeLmFB9z0feJf9N
Responses
200

Payment logs fetched successfully.

Response Schema: application/json
status
string

Status of the request. Should be success if the request didn't fail.
is_paid
boolean

true if is paid.
is_pending
boolean

true if is pending blockchain confirmation.
is_expired
boolean

true if is expired (any payment sent to the generated addresses after expiration will be disregarded).
is_partial
boolean

true if is partially paid. Might happen if the amount transferred to the generated address is below the total.
Array of objects

Detailed information about each payment option (whether is paid, partial, etc).

Array of objects

A list of notifications sent regarding payment processing, including the request details and the server's response.

400

Your request couldn't be processed, please try again later

401

Unauthorized. Invalid API key.

get/checkout/logs/
Request samples
Response samples
application/json
{
  • "status": "success",
  • "is_paid": true,
  • "is_pending": false,
  • "is_expired": false,
  • "is_partial": false,
  • "payment_data": [
    ],
  • "notifications": []
}

IPN for PaymentsWebhook


IPN issued when the payment has been confirmed by the network. Will be sent to the URL provided in notify_url.

Notes:

  • Sent via POST if post=1 parameter set, else sent via GET
  • We advise whitelisting our server IPs in order to avoid issues with the callbacks: 145.239.119.223 and 135.125.112.47
  • To prevent repeated IPNs sent to your systems, please respond with *ok* to our IPNs.
Request
query Parameters
payment_url
string

Payment link where the payment came from.
Example: payment_url=https://pay.blockbee.io/payment/fG78jtx96ugjtu0eIbeLmFB9z0feJf9N
redirect_url
string

Redirect URL provided when requesting a new payment link.
Example: redirect_url=https://example.com/success/?order_id=12345
value
number

Amount in FIAT you requested when creating the payment link.
Example: value=20000
success_token
string

Security token only known to your systems so you can make sure the order was actually paid by your customer.
Example: success_token=fG78jtx96ugjtu0eIbeLmFB9z0feJf9NfG78jtx96ugjtu0eIbeLmFB9z0feJf9N
currency
string

FIAT currency. Should be the same that you set in your Payment Settings at BlockBee's Dashboard.
Example: currency=usd
is_paid
string
Default: 1

Should always be 1.
Example: is_paid=1
paid_amount
string

Amount paid in cryptocurrency.

Notes:

  • The cryptocurrency/token used to make the payment is described in the parameter paid_coin.
Example: paid_amount=1.23
paid_coin
string

Cryptocurrency/token used to make the payment.

Notes:

  • The amount paid will be available in the parameter paid_amount.
Example: paid_coin=btc
exchange_rate
number

Exchange rate at the time of the payment.
Example: exchange_rate=20000
txid
string

Transaction hash(es) of your client's payment(s).

Notes:

  • If multiple means your customer had to make multiple transactions to fulfill the payment, since the Checkout page supports partial payments.
Example: txid=0xa7551df44e487f9c0507d68d90193cde2604dfcefdc975bae54535a2e0f80b32,0x6e8b278e3db1948d2c694b7f709dd4e864ae80d516970ebfd05a98629b6efe15,0x387c6250b3e86f7372b9c49d00497f1b26b373d40801c9e60a97ef5124b6b75c
address
string

Address generated by BlockBee where your client's payment was received.
Example: address=3PFoGK63cVVUWnd2vu7W1kM83NXUfvzMqM
status
string

Status of the transaction.
Example: status=done
Responses
200

Expected response from your server.

The callback will be marked as successful when it receives the following response from your server.

Response Schema: text/plain
string
Response samples
text/plain
*ok*

Checkout - Deposits

Documentation on how to use our ready-made Checkout page to receive cryptocurrency deposits.

Check the demo!

Before using the Checkout page (Failing to do so will lead to errors when requesting a Deposit link):

Create a Checkout Deposit

This method allows you to create a new Deposit link.

Request
query Parameters
apikey
required
string

API Key provided by BlockBee's Dashboard.
Unsure how to get yours? Check this tutorial.
currency
string

Set the FIAT currency used in the deposit page.

Note: Will override the FIAT currency set in your Payment Settings at BlockBee's Dashboard.

FIAT currencies supported in this list are (if the FIAT currency you wish to use is not in this list, you may contact us in order to add it to our service):

  • (USD) United States Dollar
  • (EUR) Euro
  • (GBP) Great Britain Pound
  • (CAD) Canadian Dollar
  • (JPY) Japanese Yen
  • (AED) UAE Dollar
  • (MYR) Malaysian Ringgit
  • (IDR) Indonesian Rupiah
  • (THB) Thai Baht
  • (CHF) Swiss Franc
  • (SGD) Singapore Dollar
  • (RUB) Russian Ruble
  • (ZAR) South African Rand
  • (TRY) Turkish Lira
  • (LKR) Sri Lankan Rupee
  • (RON) Romanian Leu
  • (BGN) Bulgarian Lev
  • (HUF) Hungarian Forint
  • (CZK) Czech Koruna
  • (PHP) Philippine Peso
  • (PLN) Poland Zloti
  • (UGX) Uganda Shillings
  • (MXN) Mexican Peso
  • (INR) Indian Rupee
  • (HKD) Hong Kong Dollar
  • (CNY) Chinese Yuan
  • (BRL) Brazilian Real
  • (DKK) Danish Krone
  • (TWD) New Taiwan Dollar
  • (AUD) Australian Dollar
  • (NGN) Nigerian Naira
  • (SEK) Swedish Krona
  • (NOK) Norwegian Krone

Some cryptocurrencies are also accepted in this field (for the conversion of the value):

  • (BTC) Bitcoin
  • (ETH) Ethereum
  • (USDT) Tether USDt
  • (USDC) USD Coin
Example: currency=eur
notify_url
required
string

URL where our system will send a payment notification (IPN), when a deposit is made.

Notes:

  • We advise you to URL Encode the notify URL, otherwise the GET parameters you add may be lost.
  • GET parameters you add to the notify URL will be sent as GET, even if you enable the post parameter.
  • For a complete list of fields sent by our system, please refer to our IPN for Deposits documentation.
  • To prevent repeated IPNs to your systems, the response to the IPN request should be *ok* in plain text.
Example: notify_url=https://example.com?user_id=1124
item_description
string

Description of the product or service being paid. This information will appear on the Checkout page.
post
number
Default: 0

Set this to 1 if you wish to receive the IPN as a POST request.

If set to 0, API will default to GET.

Notes:

  • GET parameters you added to the notify_url URL will still be sent as GET.
Example: post=1
Responses
200

Deposit URL was created successfully.

Response Schema: application/json
status
string

Status of the request. Should be success if the request didn't fail.
payment_url
string

Payment URL where your customer should be redirected to initiate the transaction.

Note: It's possible to pre-select a cryptocurrency for the checkout page by using the coin GET parameter.
* All of our supported tickers can be found at our cryptocurrencies page. Please replace the / with a _.
* Example: In order to pre-select Bitcoin for the payment, append ?coin=trc20_usdt to the payment_url as the following example: https://pay.blockbee.io/deposit/fG78jtx96ugjtu0eIbeLmFB9z0feJf9N?coin=trc20_usdt.
payment_id
string

ID of the deposit. May be used with the logs endpoint.
400

Your request couldn't be processed, please try again later

get/deposit/request/
Request samples
Response samples
application/json
{}

Retrieve Deposit Logs

Fetches logs of all deposits made to your Deposit link, including transaction details, value in fiat currency, and the status of each deposit. This endpoint is essential for tracking incoming payments and ensuring they are correctly processed and reconciled in your system.

Request
query Parameters
apikey
required
string

API Key provided by BlockBee's Dashboard.
Unsure how to get yours? Check this tutorial.
token
required
string

Deposit Token provided upon requesting the payment.

Example: token=fG78jtx96ugjtu0eIbeLmFB9z0feJf9N
Responses
200

A list of deposit transactions made to your account.

Response Schema: application/json
status
string
Array of objects
total_deposited
string

The total amount deposited.

currency
string

The fiat currency used for the value_fiat field.

Array of objects

Notifications sent regarding deposit processing.

400

Bad request. Invalid request parameters.

401

Unauthorized. Invalid API key.

get/deposit/logs/
Request samples
Response samples
application/json
{}

IPN for DepositsWebhook

IPN issued when the deposit has been confirmed by the network. Will be sent to the URL provided in notify_url.

Notes:

  • Sent via POST if post=1 parameter set, else sent via GET
  • We advise whitelisting our server IPs in order to avoid issues with the callbacks: 145.239.119.223 and 135.125.112.47
  • To prevent repeated IPNs sent to your systems, please respond with *ok* to our IPNs.
Request
query Parameters
uuid
string

This is an unique identifier to each payment your clients have made, so you can easily track any duplicate IPNs sent, in the case our system doesn't mark the IPN as successful.

Notes:

  • Our system will mark the IPN as successful as long your system replies with a plain text page containing only a *ok.
Example: uuid=afe11bea-768b-47ae-ba0f-907379fbe5ef
txid
string

Transaction hash of your client's deposit.
Example: txid=0xa7551df44e487f9c0507d68d90193cde2604dfcefdc975bae54535a2e0f80b32
address
string

Address generated by BlockBee where your client's payment was received.
Example: address=3PFoGK63cVVUWnd2vu7W1kM83NXUfvzMqM
payment_url
string

Deposit link where the deposit came from.
Example: payment_url=https://pay.blockbee.io/deposit/fG78jtx96ugjtu0eIbeLmFB9z0feJf9N
currency
string

FIAT currency. Should be the same that you set in your Payment Settings at BlockBee's Dashboard.
Example: currency=usd
paid_amount
string

Amount paid in cryptocurrency.

Notes:

  • The cryptocurrency/token used to make the payment is described in the parameter paid_coin.
Example: paid_amount=1.23
paid_amount_fiat
string

Amount paid in the FIAT currency described in the parameter currency.
Example: paid_amount_fiat=21234.32
paid_coin
string

Cryptocurrency/token used to make the payment.

Notes:

  • The amount paid will be available in the parameter paid_amount.
Example: paid_coin=btc
status
string

Status of the transaction.
Example: status=done
Responses
200

Expected response from your server

The callback will be marked as successful when it receives the following response from your server

Response Schema: text/plain
string
Response samples
text/plain
*ok*

Payouts

Automated or Manual Payouts API that allows to send funds to multiple addresses.
Payouts can now be fulfilled automatically using our dedicated API endpoints. This streamlines the transaction process, allowing you to send funds to up to 100 different addresses with a single transaction, without the need for manual selection and approval.

However, you can still fulfil Payouts from BlockBee Dashboard using your own wallet.

Notes:

  • To send tokens (eg. USDT over Polygon) your Payout Wallet is required to have the native token (eg MATIC) to pay the blockchain fees.
  • It's important to distinguish a Payout Request from a Payout.
  • A Payout Request involves the transfer of funds to a designated address.
  • A Payout constitutes the execution of a Payout Request.
  • Access to the Automated Payouts endpoints requires an API Key V2.
  • Manually fulfilling Payouts is available only for Ethereum (ERC-20), Binance Smart Chain (BSC) (BEP-20), Polygon, and Tron (TRC-20).

List Payout Requests


Using this endpoint you can fetch the Payout Requests created for your API Key and the ticker provided.

Notes:

  • This endpoint is paginated and will show only 50 Payout Requests per page.
Request
path Parameters
ticker
required
string

The ticker parameter in this API request refers to the unique identifier of the cryptocurrency to which you are making the request. It is included in the URL of the request and helps to specify the exact cryptocurrency that you want to retrieve data for. The ticker is typically a short code that uniquely identifies the cryptocurrency, or the token and it's network/blockchain.

For example, btc is the ticker for Bitcoin, and trc20/usdt is the ticker for USDT over TRC-20. Having this in mind, a request for USDT over TRC-20 will look like this: api.blockbee.io/trc20/usdt/create/.

Notes:

  • You can find all our tickers in our cryptocurrencies page.
  • Our Payouts system does not support doge.
Example: eth
query Parameters
apikey
required
string

API Key provided by BlockBee's Dashboard.
Unsure how to get yours? Check this tutorial.
status
string

Filter by the status of the Payout Request.
Enum: "all" "pending" "rejected" "processing" "done"
Example: status=all
p
number

Specify the page of the list. As this endpoint follows pagination, displaying only 50 results per page, you'll need to specify the page number to access additional results.
Example: p=2
Responses
200

List of Payout Requests.

Response Schema: application/json
status
string

Status of the response. Should be success if the operation was successful.

Array of objects

An array of payout request objects.

num_pages
integer

The number of pages of Payout Requests available.

400

Your request couldn't be processed, please try again later.

get/{ticker}/payout/request/list/
Request samples
Response samples
application/json
{
  • "status": "success",
  • "payout_requests": [
    ],
  • "num_pages": 1
}

Create a Payout Request


Use this method to create a new Payout Request, which is a request for a payment you wish to send to your customer.
Once you have created the Payout Request, you can fulfill it using BlockBee's Dashboard, or by using BlockBee API.
Request
path Parameters
ticker
required
string

The ticker parameter in this API request refers to the unique identifier of the cryptocurrency to which you are making the request. It is included in the URL of the request and helps to specify the exact cryptocurrency that you want to retrieve data for. The ticker is typically a short code that uniquely identifies the cryptocurrency, or the token and it's network/blockchain.

For example, btc is the ticker for Bitcoin, and trc20/usdt is the ticker for USDT over TRC-20. Having this in mind, a request for USDT over TRC-20 will look like this: api.blockbee.io/trc20/usdt/create/.

Notes:

  • You can find all our tickers in our cryptocurrencies page.
  • Our Payouts system does not support doge.
Example: eth
query Parameters
apikey
required
string

API Key provided by BlockBee's Dashboard.
Unsure how to get yours? Check this tutorial.
address
required
string

Provide the destination address where you want the Payout to be sent.
Example: address=TGfBcXvtZKxxku4X8yx92y56HdYTATKuDF
value
required
number

Amount you wish to send to the provided destination address.
Example: value=1.34
Responses
200

Payout Request created successfully

Response Schema: application/json
status
string

Status of the request. Should be success if the request didn't fail.

request_id
string

ID of the Payout Request.

400

Your request couldn't be processed, please try again later

get/{ticker}/payout/request/create/
Request samples
Response samples
application/json
{
  • "status": "success",
  • "request_id": "3825d29b-7a8f-47da-8623-e99850674247"
}

Create multiple Payout Requests


Use this method to create multiple Payout Requests.

Notes:

  • A Payout Request represents a payment request initiated to facilitate a transaction with your customer.
Request
path Parameters
ticker
required
string

The ticker parameter in this API request refers to the unique identifier of the cryptocurrency to which you are making the request. It is included in the URL of the request and helps to specify the exact cryptocurrency that you want to retrieve data for. The ticker is typically a short code that uniquely identifies the cryptocurrency, or the token and it's network/blockchain.

For example, btc is the ticker for Bitcoin, and trc20/usdt is the ticker for USDT over TRC-20. Having this in mind, a request for USDT over TRC-20 will look like this: api.blockbee.io/trc20/usdt/create/.

Notes:

  • You can find all our tickers in our cryptocurrencies page.
  • Our Payouts system does not support doge.
Example: eth
query Parameters
apikey
required
string

API Key provided by BlockBee's Dashboard.
Unsure how to get yours? Check this tutorial.
Request Body schema: application/json
required
object

A JSON object containing the mapping of payout destination addresses to the amounts to be paid out.

Responses
200

Success response indicating the creation of multiple Payout Requests.

Response Schema: application/json
status
string

Status of the response, indicating the successful creation of Payout Requests.

request_ids
Array of strings

An array of request IDs for the newly created Payout Requests.

400

Your request couldn't be processed, please try again later

post/{ticker}/payout/request/bulk/
Request samples
application/json
{
  • "outputs": {
    }
}
Response samples
application/json
{
  • "status": "success",
  • "request_ids": [
    ]
}

Create and Send multiple Payout Requests


Use this method to efficiently generate and dispatch multiple Payout Requests. This process not only facilitates the creation of one or several Payout Requests but also initiates the Payout, ensuring the automatic transfer of funds.
Request
path Parameters
ticker
required
string

The ticker parameter in this API request refers to the unique identifier of the cryptocurrency to which you are making the request. It is included in the URL of the request and helps to specify the exact cryptocurrency that you want to retrieve data for. The ticker is typically a short code that uniquely identifies the cryptocurrency, or the token and it's network/blockchain.

For example, btc is the ticker for Bitcoin, and trc20/usdt is the ticker for USDT over TRC-20. Having this in mind, a request for USDT over TRC-20 will look like this: api.blockbee.io/trc20/usdt/create/.

Notes:

  • You can find all our tickers in our cryptocurrencies page.
  • Our Payouts system does not support doge.
Example: eth
query Parameters
apikey
required
string

API Key provided by BlockBee's Dashboard.
Unsure how to get yours? Check this tutorial.
Request Body schema: application/json
required
object

A JSON object containing the mapping of payout destination addresses to the amounts to be paid out.

Responses
200

Payout Request created successfully

Response Schema: application/json
status
string

Status of the request. Should be success if the request didn't fail.

object
queued
boolean

Indicates whether the payout is queued for processing.

400

Your request couldn't be processed, please try again later

post/{ticker}/payout/request/bulk/process/
Request samples
application/json
{
  • "outputs": {
    }
}
Response samples
application/json
{
  • "status": "success",
  • "payout_info": {
    },
  • "queued": true
}

List Payouts


Using this endpoint you can fetch the Payout created for your API Key and the ticker provided.

Notes:

  • This endpoint will list only the Payout, which is an aggregation of the Payout Requests.
  • This endpoint is paginated and will show only 50 Payout Requests per page.
Request
path Parameters
ticker
required
string

The ticker parameter in this API request refers to the unique identifier of the cryptocurrency to which you are making the request. It is included in the URL of the request and helps to specify the exact cryptocurrency that you want to retrieve data for. The ticker is typically a short code that uniquely identifies the cryptocurrency, or the token and it's network/blockchain.

For example, btc is the ticker for Bitcoin, and trc20/usdt is the ticker for USDT over TRC-20. Having this in mind, a request for USDT over TRC-20 will look like this: api.blockbee.io/trc20/usdt/create/.

Notes:

  • You can find all our tickers in our cryptocurrencies page.
  • Our Payouts system does not support doge.
Example: eth
query Parameters
apikey
required
string

API Key provided by BlockBee's Dashboard.
Unsure how to get yours? Check this tutorial.
status
string

Filter by the status of the Payout.
Enum: "created" "processing" "done" "error"
Example: status=all
p
number

Specify the page of the list. As this endpoint follows pagination, displaying only 50 results per page, you'll need to specify the page number to access additional results.
Example: p=2
Responses
200

List of Payouts.

Response Schema: application/json
status
string

Status of the response. Should be success if the operation was successful.

Array of objects

An array of payout objects.

num_pages
integer

The number of pages of payout requests available.

400

Your request couldn't be processed, please try again later.

get/{ticker}/payout/list/
Request samples
Response samples
application/json
{
  • "status": "success",
  • "payouts": [
    ],
  • "num_pages": 1
}

Get Payout Wallet Address


Using this endpoint you can fetch the Payout Wallet address for your API Key and the ticker provided.
Request
path Parameters
ticker
required
string

The ticker parameter in this API request refers to the unique identifier of the cryptocurrency to which you are making the request. It is included in the URL of the request and helps to specify the exact cryptocurrency that you want to retrieve data for. The ticker is typically a short code that uniquely identifies the cryptocurrency, or the token and it's network/blockchain.

For example, btc is the ticker for Bitcoin, and trc20/usdt is the ticker for USDT over TRC-20. Having this in mind, a request for USDT over TRC-20 will look like this: api.blockbee.io/trc20/usdt/create/.

Notes:

  • You can find all our tickers in our cryptocurrencies page.
  • Our Payouts system does not support doge.
Example: eth
query Parameters
apikey
required
string

API Key provided by BlockBee's Dashboard.
Unsure how to get yours? Check this tutorial.
Responses
200

Response with the Payout Wallet address for the provided ticker.

Response Schema: application/json
status
string

Status of the request. Should be success if the request didn't fail.

address
string

Address of your Payout Wallet.

400

Your request couldn't be processed, please try again later

get/{ticker}/payout/address/
Request samples
Response samples
application/json
{
  • "status": "success",
  • "address": "0x18B211A1Ba5880C7d62C250B6441C2400d588589"
}

Get Payout Wallet Balance


Using this endpoint you can fetch the Payout Wallet address balance for your API Key and the ticker provided.
Request
path Parameters
ticker
required
string

The ticker parameter in this API request refers to the unique identifier of the cryptocurrency to which you are making the request. It is included in the URL of the request and helps to specify the exact cryptocurrency that you want to retrieve data for. The ticker is typically a short code that uniquely identifies the cryptocurrency, or the token and it's network/blockchain.

For example, btc is the ticker for Bitcoin, and trc20/usdt is the ticker for USDT over TRC-20. Having this in mind, a request for USDT over TRC-20 will look like this: api.blockbee.io/trc20/usdt/create/.

Notes:

  • You can find all our tickers in our cryptocurrencies page.
  • Our Payouts system does not support doge.
Example: eth
query Parameters
apikey
required
string

API Key provided by BlockBee's Dashboard.
Unsure how to get yours? Check this tutorial.
Responses
200

Response with the Payout Wallet address for the provided ticker.

Response Schema: application/json
status
string

Status of the request. Should be success if the request didn't fail.

balance
number

Balance of your Payout Wallet address for the selected ticker.

400

Your request couldn't be processed, please try again later

get/{ticker}/payout/balance/
Request samples
Response samples
application/json
{
  • "status": "success",
  • "balance": 0.02
}

Process Payout by ID


Use this endpoint to process a specific Payout using its ID.

Notes:

  • Will throw an error if the Payout status is already Done.
Request
query Parameters
apikey
required
string

API Key provided by BlockBee's Dashboard.
Unsure how to get yours? Check this tutorial.
Request Body schema: application/x-www-form-urlencoded
required
payout_id
required
integer

The ID of the payout to process.

Responses
200

Payout Request created successfully

Response Schema: application/json
status
string

Status of the request. Should be success if the request didn't fail.

object
queued
boolean

Indicates whether the payout is queued for processing.

400

Your request couldn't be processed, please try again later

post/payout/process/
Request samples
application/x-www-form-urlencoded
payout_id=12345
Response samples
application/json
{
  • "status": "success",
  • "payout_info": {
    },
  • "queued": true
}

Create Payout


Create a by providing the Payout Request ID.

Notes:

  • You can provide multiple IDs eg: 12345,54321.
Request
query Parameters
apikey
required
string

API Key provided by BlockBee's Dashboard.
Unsure how to get yours? Check this tutorial.
Request Body schema: application/x-www-form-urlencoded
required
request_ids
required
string

The ID(s) of the Payout Request(s) you wish to add to your Payout.

Responses
200

The Payout was created successfully.

Response Schema: application/json
status
string

Status of the request. Indicates success if the request has been accepted.

object
400

Your request couldn't be processed, please try again later.

post/payout/create/
Request samples
application/x-www-form-urlencoded
request_ids=12345%2C54321
Response samples
application/json
{
  • "status": "success",
  • "payout_info": {
    }
}

Check Payout Status


Check the status of your Payout by proving its ID.
Request
query Parameters
apikey
required
string

API Key provided by BlockBee's Dashboard.
Unsure how to get yours? Check this tutorial.
Request Body schema: application/x-www-form-urlencoded
required
payout_id
required
integer

The ID of the payout to process.

Responses
200

The Payout was created successfully.

Response Schema: application/json
status
string

Status of the request. Indicates success if the request has been accepted.

object
400

Your request couldn't be processed, please try again later.

post/payout/status/
Request samples
application/x-www-form-urlencoded
payout_id=e7408219-b37c-4e24-8a71-78f0755468d8
Response samples
application/json
{
  • "status": "success",
  • "payout_info": {
    }
}