> ## Documentation Index
> Fetch the complete documentation index at: https://www.bitnob.dev/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> Bitnob API requests authenticate with an `X-Auth-Client` API key header against https://api.bitnob.com.
> Always use the sandbox environment for testing. Never put live API keys in sample code.
> Money amounts are integers in the smallest unit of the currency (satoshis for BTC, cents for fiat). Never use floats.
> Every state-changing request takes a client-supplied `reference` and must be treated as idempotent on retry.
> Quotes expire. Re-quote rather than reusing a stale quote id.

# Trading UX implementation guidelines

> Concrete requirements for quote presentation, countdowns, states, and error handling in a trading UI.

## Quote presentation

Requirements:

Show exact values returned from POST /api/trading/quotes: see [Quotes](https://www.bitnob.dev/api-reference/trading/create-quote.md):

* `exchange.send_quantity` and `exchange.receive_quantity`, `price`, and `expires_at`
* Display a countdown timer (`expires_at` minus now) prominently

Format monetary values:

* USDT → \$100.00
* BTC → 225,000 sats
* NGN → ₦5,000
* Rate → 2,250 sats per \$1

UI Examples:

* “You’re converting: \$100.00”
* “You’ll receive: 225,000 sats”
* “Rate: 2,250 sats per \$1”
* “Fee: \$0.80”
* “Quote valid for: 8 seconds”

## Expiration logic

Requirements: Disable “Confirm” button as soon as `expires_at` has passed

Show a non-blocking notification:

> “Quote expired. Please refresh for a new price.”

Optionally provide:

* Auto-refresh quote after expiration
* Manual “Get New Quote” button

## Trade confirmation feedback

Requirements: After user confirms:

Show progress indicator (modal or inline stepper)

Reflect each step of backend trade lifecycle:

* Quote validation
* Balance verification
* Execution
* Wallet credit
* Confirm only after [Get Order By ID](https://www.bitnob.dev/api-reference/trading/get-order-by-id-or-reference.md) returns status = filled

Suggested UI:

* \[✓] Quote locked
* \[✓] Balance available
* \[✓] Trade executed
* \[✓] Funds credited

## Input field logic

Requirements: Input field must:

Accept only valid numbers

Internally normalize to the smallest unit:

* USDT and USDC → base units, 6 decimals (100000000 = \$100.00)
* BTC → sats (225000 = 0.00225 BTC)
* NGN → kobo (500000 = ₦5,000)

The trading API takes and returns major-unit decimal strings (`"100"` is 100 USDT, `"5000"` is ₦5,000), so convert when you build the request. See [Currencies and amounts](https://www.bitnob.dev/docs/getting-started/core-concepts-and-architecture/currencies-and-amounts.md#units-by-product).

Display labels:

* “Enter amount in USD”
* “Enter amount in bitcoin (BTC)”
* “Enter amount in Naira (NGN)”
* Show live preview of converted value

## Post-trade success page

Must Display:

* inputAmount, outputAmount
* rate used Destination wallet label
* Trade reference Timestamp (optional)

Example:

* Trade Successful
* You converted: \$100.00
* You received: 225,000 sats Rate: 2,250 sats per \$1
* Wallet: BTC Wallet
* Reference: trade\_4837ABC

## Failure handling

Required Error States:

| Condition | Ux Message |
| - | - |
| Quote expired | This quote has expired. Please request a new quote. |
| Insufficient balance | You do not have enough balance to complete this trade. |
| Quote already used (NGN) | This price has already been used. Please request a new quote. |
| Execution failure | Trade failed. No funds were moved. Try again later. |

Provide a dismissible alert and log internally with full context.

## Visual hierarchy

Priorities:

* Input/output clarity
* Rate integrity
* Quote expiry countdown
* Confirmation status
* Success/Failure state

Use consistent typography and spacing to reinforce the idea that every number is important and intentional.

## Visual language

Do not use animations that introduce uncertainty

Avoid color-coding outcomes (e.g., green for BTC, red for USDT) unless backed by semantics

Use iconography sparingly, prioritize text

Confirm actions with checkmarks, not emojis or confetti


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.