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

# Market Data API — orderbook, ticker, and charts

> Query live market data for Dubu trading pairs: browse available pairs, fetch the live orderbook, get 24-hour ticker stats, and retrieve OHLCV candlestick data.

The market data endpoints give you real-time and historical price information for all supported trading pairs. Use these endpoints to build trading dashboards, calculate order impact, or power charting interfaces. All market data routes require authentication via API key or JWT bearer token.

## Supported trading pairs

Dubu currently supports the following pairs:

| Symbol     | Description                  |
| ---------- | ---------------------------- |
| `USDT-NGN` | Tether USD vs Nigerian Naira |
| `USDC-NGN` | USD Coin vs Nigerian Naira   |
| `USD-NGN`  | US Dollar vs Nigerian Naira  |

***

## List trading pairs

```
GET /trading/market/pairs
```

Returns metadata for all active trading pairs, including minimum order sizes and precision settings.

### Example

```bash theme={null}
curl https://api.dubupay.com/api/v1/trading/market/pairs \
  -H "X-Api-Key: dubu_sk_live_YOUR_API_KEY"
```

### Response fields

<ResponseField name="symbol" type="string">
  The trading pair identifier, e.g. `USDT-NGN`.
</ResponseField>

<ResponseField name="base_asset" type="string">
  The asset being bought or sold, e.g. `USDT`.
</ResponseField>

<ResponseField name="quote_asset" type="string">
  The asset used for pricing, e.g. `NGN`.
</ResponseField>

<ResponseField name="status" type="string">
  Whether the pair is `active` or `inactive`.
</ResponseField>

***

## Get the orderbook

```
GET /trading/market/orderbook
```

Returns the current state of the live orderbook for a given pair, showing aggregated bid and ask price levels up to the requested depth.

### Query parameters

<ParamField query="symbol" type="string" required>
  The trading pair to query. One of `USDT-NGN`, `USDC-NGN`, or `USD-NGN`.
</ParamField>

<ParamField query="depth" type="number">
  Number of price levels to return for each side (bids and asks). Defaults to `20`.
</ParamField>

### Example

```bash theme={null}
curl "https://api.dubupay.com/api/v1/trading/market/orderbook?symbol=USDT-NGN&depth=5" \
  -H "X-Api-Key: dubu_sk_live_YOUR_API_KEY"
```

### Response fields

<ResponseField name="symbol" type="string">
  The trading pair.
</ResponseField>

<ResponseField name="bids" type="array">
  Array of `[price, quantity]` pairs for the buy side, sorted from highest to lowest price.
</ResponseField>

<ResponseField name="asks" type="array">
  Array of `[price, quantity]` pairs for the sell side, sorted from lowest to highest price.
</ResponseField>

<ResponseField name="timestamp" type="string">
  ISO 8601 timestamp of when the snapshot was taken.
</ResponseField>

### Example response

```json theme={null}
{
  "success": true,
  "data": {
    "symbol": "USDT-NGN",
    "bids": [
      ["1579.00", "200.00"],
      ["1578.50", "500.00"]
    ],
    "asks": [
      ["1580.00", "150.00"],
      ["1580.50", "300.00"]
    ],
    "timestamp": "2024-01-15T10:30:00.000Z"
  }
}
```

***

## Get ticker

```
GET /trading/market/ticker
```

Returns the latest price and 24-hour rolling statistics for one or all trading pairs. If you omit `symbol`, ticker data for all pairs is returned.

### Query parameters

<ParamField query="symbol" type="string">
  The trading pair to query, e.g. `USDT-NGN`. Omit to get tickers for all pairs.
</ParamField>

### Example

```bash theme={null}
curl "https://api.dubupay.com/api/v1/trading/market/ticker?symbol=USDT-NGN" \
  -H "X-Api-Key: dubu_sk_live_YOUR_API_KEY"
```

### Response fields

<ResponseField name="symbol" type="string">
  The trading pair.
</ResponseField>

<ResponseField name="price" type="string">
  Current best price for the pair.
</ResponseField>

<ResponseField name="volume_24h" type="string">
  Total base asset volume traded in the last 24 hours.
</ResponseField>

<ResponseField name="change_24h" type="string">
  Absolute price change over the last 24 hours.
</ResponseField>

<ResponseField name="change_pct_24h" type="string">
  Percentage price change over the last 24 hours.
</ResponseField>

<ResponseField name="high_24h" type="string">
  Highest price in the last 24 hours.
</ResponseField>

<ResponseField name="low_24h" type="string">
  Lowest price in the last 24 hours.
</ResponseField>

***

## Get candlestick data (klines)

```
GET /trading/market/klines
```

Returns OHLCV (open, high, low, close, volume) candlestick data for charting. You can specify a time interval, limit the number of candles returned, and optionally filter by a start and end timestamp.

### Query parameters

<ParamField query="symbol" type="string" required>
  The trading pair. One of `USDT-NGN`, `USDC-NGN`, or `USD-NGN`.
</ParamField>

<ParamField query="interval" type="string" required>
  Candle interval. Examples: `1m`, `5m`, `15m`, `1h`, `4h`, `1d`.
</ParamField>

<ParamField query="limit" type="number">
  Maximum number of candles to return. Defaults to `100`.
</ParamField>

<ParamField query="start" type="number">
  Start of the time range as a Unix timestamp in milliseconds. Optional.
</ParamField>

<ParamField query="end" type="number">
  End of the time range as a Unix timestamp in milliseconds. Optional.
</ParamField>

### Example

```bash theme={null}
curl "https://api.dubupay.com/api/v1/trading/market/klines?symbol=USDT-NGN&interval=1h&limit=24" \
  -H "X-Api-Key: dubu_sk_live_YOUR_API_KEY"
```

### Response fields

Each element in the `data` array represents one candle.

<ResponseField name="open_time" type="number">
  Unix timestamp in milliseconds for the start of this candle.
</ResponseField>

<ResponseField name="open" type="string">
  Opening price.
</ResponseField>

<ResponseField name="high" type="string">
  Highest price during the interval.
</ResponseField>

<ResponseField name="low" type="string">
  Lowest price during the interval.
</ResponseField>

<ResponseField name="close" type="string">
  Closing price.
</ResponseField>

<ResponseField name="volume" type="string">
  Base asset volume traded during the interval.
</ResponseField>

<ResponseField name="close_time" type="number">
  Unix timestamp in milliseconds for the end of this candle.
</ResponseField>