Currency methods
B2BINPAY currency API methods for supported cryptocurrencies, currency data, and denomination management via REST API
For a human-readable list of supported currencies, see Currency codes.
Currency object
| Name | Type | Description |
|---|---|---|
id |
string | The unique system identifier of a currency, matching the ISO code. |
blockchain_name |
string |
The name of a blockchain, for example: The value is filled in by default only for coins. For other currencies, the value is an empty string. |
iso |
number | The ISO code of a currency. |
name |
string | The name of a currency, for example: Bitcoin. |
alpha |
string |
The alphabetic code of a currency, for example For tokens, the code includes the network, for example |
alias |
string or null |
The common ticker of the same asset on different networks, for example
|
tags |
string | The tags assigned via the B2BINPAY Back Office. |
exp |
number | The currency precision, that is the number of digits after the decimal separator. |
confirmation_blocks |
number or null |
For cryptocurrencies, the default number of blocks needed to send a callback. For fiat and virtual currencies, |
minimal_transfer_amount |
string | The minimum possible amount of transfers. |
minimal_payout_amount |
string | The minimum possible payout amount in this currency. |
block_delay |
number |
For cryptocurrencies, the estimated block mining time, in seconds. For fiat and virtual currencies, |
tag_allowed |
boolean | true if addresses in this currency require a destination tag or memo, for example XRP, XLM, or GRAM. In this case, pass the tag together with the payout address. |
parent |
object |
For tokens only. The parent currency of a token, that is, the native coin of the same blockchain. For other currencies, returns The object contains the string |
Currency object example
{
"type": "currency",
"id": "2015",
"attributes": {
"blockchain_name": "",
"iso": 2015,
"name": "TetherUS",
"alpha": "USDT-ETH",
"alias": "USDT",
"tags": "",
"exp": 6,
"confirmation_blocks": 3,
"minimal_transfer_amount": "25.000000",
"minimal_payout_amount": "25.000000",
"block_delay": 75,
"tag_allowed": false
},
"relationships": {
"parent": {
"data": {
"type": "currency",
"id": "1002"
}
}
}
}Use cases
Use the currency methods to keep your integration in sync with the currencies supported by B2BINPAY instead of hard-coding them. The scenarios below cover the typical needs of CRM, PSP, and cashier integrations.
Currency codes on the sandbox and production environments differ. Build the currency dictionary separately for each environment and store the iso value, not the ticker: tickers can be renamed, the iso code never changes.
Build a local currency dictionary
Request the whole list once at start-up and then refresh it on a schedule, for example daily:
curl --request GET \
--url '[base]/currency/?get_all=true' \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/vnd.api+json'Store iso, alpha, alias, exp, and the parent ID of every currency. Use iso in deposit, payout, and wallet requests and when matching the currency relationship in callbacks.
Offer the correct network for an asset
When a payer selects an asset such as USDT, show only the networks supported by B2BINPAY and send the iso of the selected network currency:
curl --request GET \
--url '[base]/currency/?filter[alias]=USDT&get_all=true' \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/vnd.api+json'The response contains one object per network, for example USDT-ETH and USDT-TRX. Label each option by alpha, and resolve the network coin through the parent relationship.
Get the currencies available for a new wallet
To let a user pick a currency for a new wallet, request only the currencies in which a wallet of the required type can be created for your legal entity:
curl --request GET \
--url '[base]/currency/?filter[only_available_wallet_currencies]=1&get_all=true' \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/vnd.api+json'Use 1 for a merchant wallet, 2 for an enterprise wallet, 3 for a custody wallet, or 5 for a swap wallet. The filter applies the liquidity, currency type, and legal entity settings on the server side, so you don't need to check them yourself.
Get the currencies accepted for deposits to a wallet
To show a payer only the currencies that can be deposited to a specific wallet, pass the wallet ID:
curl --request GET \
--url '[base]/currency/?filter[available_deposit_currency_by_wallet_id]=<wallet_id>&get_all=true' \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/vnd.api+json'For an enterprise wallet, the response contains the wallet currency only. For a merchant wallet, it contains every network currency that can be converted to the wallet currency. The wallet must belong to your legal entity, otherwise the list is empty.
Get the currencies available for payouts from a wallet
To validate a withdrawal form before creating a payout, request the currencies that can be paid out from the wallet:
curl --request GET \
--url '[base]/currency/?filter[available_payout_currency_by_wallet_id]=<wallet_id>&get_all=true' \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/vnd.api+json'Combine the result with minimal_payout_amount and tag_allowed of the selected currency to validate the amount and request a destination tag when it is required.
Validate amounts and estimate crediting time
Use the cached currency object to validate operations before sending them:
- Round amounts to
expdecimal places. - Reject deposits below
minimal_transfer_amount: a smaller transfer is canceled and not credited. - Reject payouts below
minimal_payout_amount. - Ask for a destination tag or memo when
tag_allowedistrue. - Estimate the time to the confirmation callback as
confirmation_blocksmultiplied byblock_delayseconds.
Get currency
Request
GET [base]/currency/{id}
The request can contain the following path parameter.
| Name | Type | Required | Description |
|---|---|---|---|
id |
string | No |
The ISO code (for example Virtual currencies and custom tokens can be requested by ISO code only. |
For the list request, you can use the following query parameters.
| Name | Type | Description |
|---|---|---|
get_all |
boolean | true returns the whole list in one response without pagination. Recommended for building a local currency dictionary. The response then contains no links, meta, or included objects. |
page[number], page[size] |
number | Pagination according to the JSON API Specification. The default page size is 10. Ignored when get_all=true. |
sort |
string | iso, name, or alpha; add the - prefix for descending order. |
include |
string | parent adds the parent currencies of the returned tokens to the included array. Not applied together with get_all=true. |
filter[alias] |
string | The exact alias, for example USDT. Returns the same asset on every supported network. |
filter[alpha], filter[name], filter[iso] |
string | Case-insensitive partial match. |
filter[blockchain_name] |
string | The exact blockchain name, for example Ethereum. |
filter[parent] |
number | The ISO code of a parent currency. Returns its tokens. |
filter[only_available_wallet_currencies] |
number | The wallet type: 1 — Merchant, 2 — Enterprise, 3 — Custody, 5 — Swap. Returns only the currencies in which you can create a wallet of this type. |
filter[available_deposit_currency_by_wallet_id] |
number | The wallet ID. Returns only the currencies that can be deposited to this wallet. |
filter[available_payout_currency_by_wallet_id] |
number | The wallet ID. Returns only the currencies that can be paid out from this wallet. |
The following filters refer to platform settings that are not included in the currency object but can be used to narrow the list.
| Name | Type | Description |
|---|---|---|
filter[type] |
number |
The currency type: Use |
filter[token_type] |
number | The token standard: 1 — ERC20 (Ethereum), 2 — NEO, 3 — NEM, 4 — OMNI (Bitcoin), 5 — BEP20 (BNB Chain), 6 — TRC20 (Tron), 7 — ERC20 (Avalanche), 8 — ERC20 (Polygon), 9 — ERC20 (Optimism), 10 — ERC20 (Arbitrum), 11 — ERC20 (Base), 12 — SPL (Solana), 13 — ASA (Algorand), 14 — TEP74 (The Open Network). |
filter[have_liquidity] |
boolean | true returns only the currencies with liquidity available for swaps and merchant wallet operations. |
filter[is_merchant_wallet_allowed] |
boolean | true returns only the currencies in which a merchant wallet can be created. |
filter[is_swap_wallet_allowed] |
boolean | true returns only the currencies in which a swap wallet can be created. |
filter[contract] |
string | The smart contract address of a token, partial match of 16 to 128 alphanumeric characters. |
Boolean filters accept the values true and false only.
Filtering by object parameters can be applied according to the JSON API Specification.
Request example
curl --request GET \
--url [base]/currency/ \
--header 'Authorization: Bearer <token>' \
--header 'Content-Type: application/vnd.api+json'import requests
url = '[base]/currency/'
headers = {
'Authorization': 'Bearer <token>',
'Content-Type': 'application/vnd.api+json',
}
requests.get(url, headers=headers)<?php
use GuzzleHttp\Client;
use GuzzleHttp\Exception\RequestException;
$client = new GuzzleHttp\Client();
try {
$res = $client->get('[base]/currency/', [
'headers' => [
'Authorization' => 'Bearer <token>',
'Content-Type' => 'application/vnd.api+json',
],
]);
echo $res->getBody();
} catch (RequestException $e) {}Response
In case of success, the response body contains a currency object or an array of objects (if the id wasn’t specified).
The currencies list is paginated and the default page size is 10. You can adjust pagination according to the JSON API Specification. To receive the whole list in one response, add get_all=true to the request.
Response codes
| HTTP code | Application code | Description | Suggested action |
|---|---|---|---|
200
|
— | The request succeeded. | — |
400
|
invalid filter[name] | The filter name is not supported. | Use one of the filters listed above. |
401
|
2007: No active account found with the given credentials | Incorrect credentials. | Send correct credentials. |
403
|
2016: Your IP is not white listed | The request came from an IP address that is not in your legal entity’s IP whitelist. | Add the IP address in Access list → IP whitelist. See How to whitelist IP addresses. |
404
|
404: No Currency matches the given query. | The currency with the given ISO or alphabetic code wasn’t found. The alphabetic code is case-sensitive. | Send a correct id. |
500
|
— | Internal server error. | Try again later. |
502
|
— | Bad gateway. | Try again later. |
503
|
— | Service unavailable. | Try again later. |
504
|
— | Gateway timeout. | Try again later. |
5xx
|
— | Other server errors. | Try again later. |
Zuletzt aktualisiert am