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

# Exchange Overview

> Market data, order lifecycle, and status reconciliation for account trading automation.

The exchange routes let approved Stabyl accounts automate trading activity that
would otherwise be performed in the product interface. Discover markets first,
validate amounts and precision locally, submit order intents with idempotency,
consume exchange events, and reconcile periodically from order and fill reads.

## Core Objects

| Object     | Description                                                                 |
| ---------- | --------------------------------------------------------------------------- |
| Market     | A tradable pair such as `USD/NGN`, with supported order rules and precision |
| Ticker     | Current best bid/ask and 24h market statistics for a pair                   |
| Order book | Aggregated price levels available for a pair at a point in time             |
| Trade      | A recent public market execution                                            |
| Fill       | An execution linked to your account's order history                         |
| Order      | Your instruction to buy or sell a base asset against a quote asset          |

Use IDs and symbols exactly as returned by the API. Do not infer pair names, decimal precision, minimum sizes, or route availability from hardcoded configuration.

Today, the supported exchange pair is `USD/NGN`. As new pairs are added, they will appear in `GET /partner/exchange/markets`; build against discovery rather than assuming this list is permanent.

## Market Data

Market data routes are read-only and should be used before order submission and during reconciliation:

| Need                                       | Endpoint family                                                  |
| ------------------------------------------ | ---------------------------------------------------------------- |
| Discover tradable products                 | `GET /partner/exchange/markets`                                  |
| Show a current quote                       | `GET /partner/exchange/ticker/24h`                               |
| Inspect depth before placing a limit order | `GET /partner/exchange/orderbook/{pair_id}/snapshot`             |
| Draw charts or backfill candles            | `GET /partner/exchange/candles`                                  |
| Reconcile recent executions                | `GET /partner/exchange/trades` and `GET /partner/exchange/fills` |

Market data changes frequently. Treat responses as snapshots, cache only for short intervals, and refresh before sending price-sensitive orders.

## Orders

An order request is an instruction, not a guarantee that the order has fully executed. The create route validates the request, records the intent, and returns an order that may still be pending. Matching and final settlement are asynchronous.

| Order type | Use when                                                   | Required price |
| ---------- | ---------------------------------------------------------- | -------------- |
| `limit`    | You want execution at a specific price or better           | Yes            |
| `market`   | You prefer immediate execution against available liquidity | No             |

| Side   | Meaning                                       |
| ------ | --------------------------------------------- |
| `buy`  | Spend quote currency to acquire base currency |
| `sell` | Sell base currency for quote currency         |

For example, on `USD/NGN`, `USD` is the base currency and `NGN` is the quote currency.

## Order Lifecycle

Orders can move through the following statuses:

| Status             | Meaning                                           |
| ------------------ | ------------------------------------------------- |
| `pending`          | Request accepted for processing                   |
| `accepted`         | Order is live or eligible for matching            |
| `partially_filled` | Some quantity has executed                        |
| `filled`           | Full quantity has executed                        |
| `cancelled`        | Remaining quantity was cancelled                  |
| `rejected`         | Order was not accepted                            |
| `expired`          | The order expired without remaining live quantity |

Only `filled`, `cancelled`, `rejected`, and `expired` should be treated as
terminal. A `partially_filled` order still has remaining quantity unless the
order later moves to a terminal state.

## Reconciliation Pattern

1. Generate an `Idempotency-Key` and store it with the local order intent.
2. Submit the order with `POST /partner/exchange/orders`.
3. If the create response is uncertain, retry with the same `Idempotency-Key`.
4. Apply exchange webhooks or private WebSocket updates to the local order.
5. Periodically reconcile order detail, fills, and wallet transactions from REST.
6. Run reconciliation after event-consumer downtime or a connection reset.

Never assume a network timeout means an order did not exist. Query the order state before creating a replacement.

Authenticated exchange endpoints require `X-Api-Key`. Order write routes also require `Idempotency-Key`.