Best Practices for Trading

Build safe, scalable conversion experiences across USDT, USDC, Bitcoin, and NGN.

Trading involves real-time pricing, user input, and asset movement. To ensure reliability and protect both your users and your internal systems, follow these best practices.

Use Quote Locking for Predictable User Experience

Whenever you present pricing to an end user:

Use POST /api/trading/quotes to fetch a quote — see Quotes

Store the quoteId on your backend

Use the quoteId in your POST /api/trading/orders call — see Create Order — within the validity window (about 30 seconds in development, 10 seconds in production)

Why: This guarantees your user receives exactly the rate they saw — no surprises due to market volatility.

If you skip the quote, the trade executes at the best available live rate.

For NGN pairs, quote locking is mandatory — naira orders must include a quote_id, so they cannot execute at a live market rate.

Always Use a Unique reference per Trade

Every trade should include a globally unique reference ID:

Use a UUID or transaction-specific string (e.g. user123_swap_001)

This ensures idempotency — replays or retries return the same result

Prevents duplicate execution of trades due to network timeouts or retries

React to Webhooks, Not Just Synchronous Responses

The /api/trading/orders response returns immediately, but for production environments:

Wait for trade.completed webhook to update balances or mark the trade as “done”

Log trade.failed events to capture failure reasons and retry or notify the user

This allows you to build event-driven trade state management, which is more reliable at scale.

Track and Reconcile All Trade Activity

Reconcile against Get Orders, and resolve individual trades with Get Order By ID. Log the following in your internal ledger per trade:

reference, tradeId

from, to, rate, inputAmount, outputAmount

status (completed or failed)

createdAt timestamp

Run daily or hourly reconciliation:

Match your ledger entries with /api/trading/orders history

Match trade amounts with corresponding wallet debits/credits

Investigate any trades that were initiated but lack final webhook confirmation

Handle Quote Expiry Gracefully

If a quote expires before trade execution — you can re-read its state with Get Quote by ID:

You will receive a 400 response with reason: "Quote expired"

Return a clear message to the user:

“The rate has expired. Please refresh the quote and try again.” Always validate quotes expiresAt timestamp server-side before use.

Validate Trade Amounts and Units

When trading from USDT, submit amount in cents (e.g., 10000 = $100.00)

When trading from BTC, submit amount in satoshis (e.g., 100000 = 0.001 BTC)

When trading from NGN, submit amount in whole naira — major units, not kobo (e.g., 5000 = ₦5,000)

Tip

Normalize user input in your frontend or backend, not at the API boundary.

Secure Your Webhooks

Use Bitnob’s signed webhook system:

Validate X-Bitnob-Signature using HMAC SHA-256 with your webhook secret

Store all received events with delivery timestamp and status

Make your webhook processor idempotent and retry-safe

Protect Against Frontend Abuses

If you're exposing trading to users:

Set min/max limits in your frontend even though Bitnob has no enforced volume limits

Throttle or queue trade attempts to prevent race conditions

Log all trade attempts for abuse or velocity monitoring

Be Transparent in Your UX

Show users:

The amount they’re converting

The output they’ll receive

The chain/asset used

Any associated fees (if applicable)

A visible "Rate locked for X seconds" timer when using quotes

This builds trust and reduces confusion during high-volatility moments.

Handle Failures Intelligently

Handle these known failure states in your code:

scenario	response code	how to respond
Quote expired	400	Fetch a new quote and retry
Duplicate reference	409	Use existing trade result (log it)
Insufficient balance	422	Prevent trade initiation, notify user, retry later
Internal execution error	500	Retry once with exponential backoff or log for review

With these patterns in place, your trading workflows will be more robust, easier to debug, and ready to scale with zero slippage and zero surprises.

Would you like to now finalize with the Error Handling Patterns section or package this whole Trading section into a structured sidebar + endpoint spec layout?