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 wallet detail endpoint to get current balances per token and chain:
Key Fields to Monitor:
balanceBefore and balanceAfter (in webhook or transfer response)
centFees: actual fee in cents deducted from your balance
available vs pending balances (if pending states exist in your account model)
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 webhook
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
Every send returns a centFees field
Gas fees are priced dynamically per chain
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 /wallets/stable-coins-networks 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:
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
| 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 | ✅ |
