Best Practices for Trading
Build safe, scalable conversion experiences across USDT and Bitcoin.
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 GET /trades/quote to fetch a quote
Store the quoteId on your backend
Use the quoteId in your POST /trades/execute call within the validity window (typically 30 seconds)
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.
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 /trades/execute 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
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 /trades 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 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)
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.
