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: Bitcoin.

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 BTC.

For tokens, the code includes the network, for example USDT-ETH or USDT-TRX. For a custom token, the code you specified in the token request is returned.

alias string or null

The common ticker of the same asset on different networks, for example USDT for USDT-ETH and USDT-TRX. Use it to group networks of one asset.

null for fiat and virtual currencies and when no alias is set.

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, null.

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, 0.

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 "data": null.

The object contains the string id field matching the parent currency ISO code. To receive the parent currency objects in the same response, add include=parent to the request.

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 exp decimal 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_allowed is true.
  • Estimate the time to the confirmation callback as confirmation_blocks multiplied by block_delay seconds.

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 2015) or the alphabetic code (for example USDT-ETH) of a currency. The alphabetic code is case-sensitive. If omitted, the list of currencies is returned.

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: 1 — coin, 2 — token, 3 — custom token, 4 — fiat currency, 5 — virtual currency, that is, an asset without a network used for merchant, swap, and custody wallets.

Use filter[type.in]=4,5 to select several types.

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

Auf dieser Seite