Advanced Topics & Best Practices for Stablecoins

This section covers deeper considerations to help your integration scale reliably, stay consistent across chains, and avoid edge-case issues in production. Think of this as the “battle-tested” part of the documentation.

Wallet Balances and Reconciliation

Querying Wallet Balances Use the Get Balances endpoint to get current balances per token and chain:

Wallet Balance Example

Key Fields to Monitor: To read a single asset instead of the full account list, use Get Balance By Currency.

field	description
ledger_balance	Total balance including pending transactions (in smallest unit, e.g., '6281647' = 6.281647 USDT)
available_balance	Funds available for immediate withdrawal or transfer (in smallest unit)
currency	Asset type (USDT, USDC, BTC)
ledger_balance_formatted	Human-readable ledger balance string (e.g., '6.281647 USDT') for display purposes
available_balance_formatted	Human-readable available balance string (e.g., '11.967069 USDC') for display purposes
company_id	The unique identifier of the company that owns the accounts

Reconciliation Strategy:

Use reference from transfer creation and webhook to link internal ledger

Set up periodic cron job (e.g., every 15 mins) to:

Sum balances per chain

Compare against Bitnob wallet balances

Flag discrepancies or unacknowledged deposits

Deposit Edge Cases

Duplicate Transfers A user may send the same amount from the same wallet twice. Rely on:

txHash in the webhook payload

address + token + chain + txHash as a unique deposit identifier

Late Confirmations or Reorgs Rare, but happens mostly on Ethereum-based chains:

A block may be reorganized, invalidating a previous confirmation

Bitnob will adjust the webhook status if needed

You should track confirmations dynamically for large transfers

Wrong Chain Deposits Example: user sends USDT to a Tron address using Ethereum by mistake. Bitnob cannot recover these—educate users clearly, and consider adding:

Frontend warnings based on selected network QR code generation that encodes chain metadata

Fee Handling

Fee Visibility

The fee for every send is a flat $1 — read it back as fee on Get Transaction By ID Or Reference; the create response does not carry a fee field

The fee is the same on every chain and for any amount, so it can be shown before the user confirms

Bitnob optimizes internally for batching and cost efficiency

Fee Optimization Tips:

Use tron, bsc, or polygon for lowest average fees

Avoid using ethereum for micro-payments

Query supported chains for each asset using /stablecoins/supported-chains — see Stablecoins Supported Chains — and suggest the cheapest one dynamically

Design Suggestion: When showing a “Send $1” flow, display:

Sending: $1.00

Network Fee: $0.01

You’ll receive: $0.99

Rate Limits and Throughput

Default Rate Limit: 60 requests/minute per API key Headers Returned: Retry-After for 429 responses

Handling Rate Limits: The full list of codes a write can return is documented under withdrawal error responses.

Queue outbound requests and retry with exponential backoff

Respect retry-after headers and avoid hammering the API

Contact support for enterprise volume upgrade

Batch Transfers? Currently one transfer per request. If you need batching:

Build queueing logic client-side

Use webhooks to drive asynchronous updates to your users

Production Checklist

Before going live, cross-check each item against the API reference: HMAC request signing, webhook signature verification, and error responses.

item	status
API keys are scoped and rotated	✅
Testnet integration is verified	✅
Webhook verification is implemented	✅
Unique reference used for all outbound transfers	✅
Retry logic added for 429, 5xx responses	✅
Monitoring set up for failed transfers	✅
Reconciliation script in place	✅
Support escalation plan documented	✅