Preparing to Work with Stablecoins

Before you begin integrating, work through the signed request examples in the API reference. It’s essential for both design and engineering teams to share a deep conceptual understanding of how stablecoin issuance, movement and settlement operate in our platform. This section focuses on the “what” and the “why,” leaving the “how” (API calls) for later.

Testnets vs Mainnets

Purpose: Testnets (e.g. Solana Devnet) let you simulate real transfers without moving real value.

Differences: confirmation times, token faucets instead of real assets, different network parameters.

Key takeaway: your workflows must behave identically in both environments—logic for retries, confirmations and error handling shouldn’t change when you swap URLs.

Wallets, Addresses and Tokens

Wallet abstraction: a logical container for balances across chains. Does not hold keys—it simply tracks how much USDC/USDT you control, readable via Get Balances.

Deposit addresses: unique on-chain addresses per wallet per chain, created with Generate Addresses. They map incoming tokens to the correct internal account.

Token standards: ERC-20 (Ethereum, Arbitrum, BSC), SPL (Solana), TRC-20 (Tron), Avalanche (AVAX), Base (base), Optimism (OP), Polygon (POL). Although standards differ, they share core functions: transfer, balanceOf, approval.

Confirmations and Finality

Block confirmations: each new block reduces risk of reorgs; the number you wait for varies by chain (e.g. 15 on Ethereum, 1 on Solana).

Finality models:

Probabilistic (Ethereum): risk decreases over time but never hits zero.

Absolute (some PoS chains): once confirmed, blocks are final.

Design impact: UI should show “1/15 confirmations” or “confirmed” states, driven by the deposit webhook; engineers must reconcile late-arriving reorgs or orphaned blocks.

Idempotency and Consistency

Why idempotency? Prevents duplicate transfers when clients retry after network errors.

Atomicity guarantee: balance updates, token issuance and notification scheduling must all succeed or none do—avoiding mismatches between on-chain and internal records.

Architectural note: treat each business event (e.g. “user requested a withdrawal”) as a single unit of work identified by a unique key — on the API that key is the reference on the withdrawal request.

Event-Driven Architecture

Webhooks vs Polling: our platform emits events when deposits or withdrawals settle; polling Get All Transactions is the failsafe, not the primary path.

Benefits: near-instant notification, simplified client logic.

Design outlook: dashboards subscribe to event streams and update balances in real time; engineers build idempotent handlers to process each event exactly once.

Core Stablecoin Workflows (Conceptual Flows)

Below are the three main on-chain stablecoin flows. Each flow is presented as a high-level sequence, key states and potential edge cases.

Deposit Flow

Key teaching points

Address generation is a purely internal mapping—no on-chain transaction needed.

Confirmation waiting is asynchronous; your UI must handle “pending” vs “confirmed.”

A late chain reorg could invalidate a deposit—design jobs to detect and reverse if needed.

Withdrawal Flow

Key teaching points

Balance lock ensures funds aren’t double-spent while the on-chain transfer remains in flight — see the withdrawal status lifecycle.

Idempotency prevents duplicate token transfers if the client retries.

Handling on-chain failure (e.g. out-of-gas) must clean up locks and inform clients; the codes are listed under Error Responses.

Internal Transfers (Netting)

When: moving stablecoins between two Bitnob wallets on the same chain.

How:

If both wallets exist internally, update balances off-chain.

Batch and net external settlement later to save fees.

Diagram: