> ## 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.

# Market Data

> Discover markets, price orders, and reconcile execution activity.

Market data routes help you discover supported pairs, show current prices, inspect order book depth, and reconcile execution activity. They are designed for backend trading automation and internal tools that need deterministic product metadata before placing orders.

| Endpoint                                             | Use                                               |
| ---------------------------------------------------- | ------------------------------------------------- |
| `GET /partner/exchange/markets`                      | Supported pairs, precision, and order constraints |
| `GET /partner/exchange/ticker/24h`                   | Current best bid/ask and 24h statistics           |
| `GET /partner/exchange/orderbook/{pair_id}/snapshot` | Bid and ask depth for a pair                      |
| `GET /partner/exchange/orderbook/{pair_id}/levels`   | One-side depth for focused quote displays         |
| `GET /partner/exchange/candles`                      | OHLCV candles for charting and historical checks  |
| `GET /partner/exchange/trades`                       | Recent public executions                          |
| `GET /partner/exchange/fills`                        | Account execution history where available         |

## Market Discovery

Call `GET /partner/exchange/markets` during startup and refresh it periodically. Use the returned values as the source of truth for:

* supported `pair_id` values
* accepted order types
* amount and price precision
* minimum and maximum order sizes
* trading status

Do not submit an order for a pair that is missing, disabled, or outside the returned limits.

The currently supported exchange pair is `USD/NGN`. Future pairs should be discovered from this endpoint when they become available.

```bash theme={null}
curl https://api-staging.stabyl.com/v1/partner/exchange/markets \
  -H "X-Api-Key: $STABYL_API_KEY"
```

## Pricing Before Order Submission

Use ticker data for lightweight quote displays. Use order book snapshots before sending a large or price sensitive order, because the top-of-book price alone does not show how much size is available.

```bash theme={null}
curl "https://api-staging.stabyl.com/v1/partner/exchange/ticker/24h?pair_id=USD/NGN" \
  -H "X-Api-Key: $STABYL_API_KEY"
```

```bash theme={null}
curl https://api-staging.stabyl.com/v1/partner/exchange/orderbook/USD%2FNGN/snapshot \
  -H "X-Api-Key: $STABYL_API_KEY"
```

## Historical Reads

Candles and trades are useful for charts, execution review, and detecting unexpected price movement. Always page through historical data using the documented query parameters instead of requesting a large range in one call.

```bash theme={null}
curl "https://api-staging.stabyl.com/v1/partner/exchange/candles?pair_id=USD/NGN&interval=1h&limit=100" \
  -H "X-Api-Key: $STABYL_API_KEY"
```

## Operational Guidance

| Pattern        | Recommendation                                           |
| -------------- | -------------------------------------------------------- |
| Startup        | Fetch markets before enabling trading automation         |
| Quote display  | Refresh ticker data on a short interval                  |
| Order entry    | Read market metadata and current price before validation |
| Reconciliation | Store order IDs, then join order reads with fills        |
| Caching        | Cache product metadata longer than live price data       |

## Required Headers

Market data endpoints require `X-Api-Key` enabled for exchange reads.

Common failures include unsupported `pair_id`, invalid time windows, malformed intervals, or requesting too many records in one call.