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

# Reading Market Data

> Retrieve tickers, order book depth, public trades, and OHLCV candles from the Busha exchange.

This guide will walk you through the public market data available on the Busha exchange: **tickers**, **order book**, **trades**, and **candles**. Each answers a different question — a ticker is a one-glance price summary, the order book shows resting depth, trades show what actually executed, and candles summarize price movement over time.

> [!TIP]
>
> **What You'll Achieve:**
>
> 1. Read a ticker for a quick price summary.
>
> 2. Retrieve order book depth for a single market.
>
> 3. List recent public trades.
>
> 4. Fetch OHLCV candles for charting.

## Prerequisites

Before you begin, ensure you have:

* A **Busha Business Account** and **Secret API Key** (from the [Quick Start Tutorial](https://docs.busha.io/guides/getting-started/quick-start.md)).

* An understanding of the API Environments (Sandbox vs. Production) and their base URLs (from the [Make Your First Request Guide](https://docs.busha.io/guides/getting-started/make-first-request.md)).

* An understanding of market symbols (from [Understanding the Exchange](https://docs.busha.io/guides/exchange/introduction.md)).

> [!NOTE]
>
> All market data endpoints are public and accept an optional bearer token. The
> only unauthenticated endpoint in this guide is the same pattern — no token is
> required, but including one keeps a single code path.

## How to Read Market Data

**1. Read a Ticker**

A **ticker** merges the 24-hour summary with the top of book in one read, so you can show a price headline without reading the whole order book.

To read the ticker for a single market:

```bash theme={null}
$ curl -i -X GET \
  https://YOUR_BASE_URL/v1/exchange/markets/USDT-NGN/ticker \
  -H 'Authorization: Bearer YOUR_SECRET_TOKEN'
```

To read every market's ticker at once, use `GET /v1/exchange/tickers` — the same payload per symbol, unpaginated.

**Expected Response:**

```json theme={null}
{
  "status": "success",
  "message": "Ticker retrieved",
  "data": {
    "symbol": "USDT-NGN",
    "last_price": "1363.45",
    "best_bid": "1363.32",
    "best_bid_quantity": "561.49",
    "best_ask": "1364.21",
    "best_ask_quantity": "352.98",
    "open_24h": "1364.31",
    "high_24h": "1364.32",
    "low_24h": "1363.22",
    "volume_24h": "102.44",
    "quote_volume_24h": "139682.48",
    "price_change_24h": "-0.86",
    "price_change_percent_24h": "-0.06",
    "trade_count_24h": 6,
    "time": "2026-10-06T14:05:32.877996175Z"
  }
}
```

<table>
  <thead>
    <tr>
      <th>Field</th>
      <th>Description</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>`last_price`</td>
      <td>The most recent trade price.</td>
    </tr>

    <tr>
      <td>`best_bid` / `best_ask`</td>
      <td>The highest buy price and lowest sell price resting in the book (the spread).</td>
    </tr>

    <tr>
      <td>`open_24h` / `high_24h` / `low_24h`</td>
      <td>The opening, highest, and lowest prices over the last 24 hours.</td>
    </tr>

    <tr>
      <td>`volume_24h` / `quote_volume_24h`</td>
      <td>Total base and quote asset traded over 24 hours.</td>
    </tr>
  </tbody>
</table>

**2. Read the Order Book**

The **order book** shows aggregated depth: how much rests at each price on the buy side (`bids`) and sell side (`asks`). Each level is a positional `[price, quantity]` pair, both decimal strings.

To read the order book:

```bash theme={null}
$ curl -i -X GET \
  "https://YOUR_BASE_URL/v1/exchange/markets/USDT-NGN/order_book?depth=5" \
  -H 'Authorization: Bearer YOUR_SECRET_TOKEN'
```

`depth` names how many levels a side returns and must be one of `1`, `5`, `10`, `20`, `50`, `100`, or `500`; omitting it returns `50`.

**Expected Response:**

```json theme={null}
{
  "status": "success",
  "message": "Order book retrieved",
  "data": {
    "sequence": 62711,
    "time": "2026-10-06T14:05:41.517270221Z",
    "bids": [
      ["1363.32", "561.49"],
      ["1363.22", "20.23"]
    ],
    "asks": [
      ["1364.21", "352.98"],
      ["1364.88", "937.59"]
    ]
  }
}
```

`bids` are best-first and descending (the highest buy price first); `asks` are best-first and ascending (the lowest sell price first). The quantity at a level is the total resting size, not one order's.

> [!NOTE]
>
> `sequence` counts accepted orders, not book changes, so do not use it to
> decide whether the depth has moved. For a live book, subscribe to the
> `order_book` stream channel instead; this REST read is for clients that
> want depth without holding a socket open.

**3. List Public Trades**

**Trades** are the market's public tape — the price and quantity of every completed match, most recent first. `taker_side` is the side that crossed the spread.

To list trades:

```bash theme={null}
$ curl -i -X GET \
  "https://YOUR_BASE_URL/v1/exchange/markets/USDT-NGN/trades?limit=3" \
  -H 'Authorization: Bearer YOUR_SECRET_TOKEN'
```

`limit` defaults to `50` and is capped at `500`. Results are cursor-paginated via `next_cursor`, and you can bound the window with `from` and `to` (RFC3339).

**Expected Response:**

```json theme={null}
{
  "status": "success",
  "message": "Trades retrieved",
  "data": [
    {
      "trade_id": "586",
      "price": "1363.45",
      "quantity": "0.1",
      "taker_side": "sell",
      "time": "2026-10-06T13:48:39.263203Z"
    },
    {
      "trade_id": "585",
      "price": "1364.32",
      "quantity": "0.1",
      "taker_side": "buy",
      "time": "2026-10-06T13:48:06.443516Z"
    }
  ],
  "pagination": {
    "current_entries_size": 3,
    "next_cursor": "NTg0Og=="
  }
}
```

**4. Fetch Candles**

A **candle** (OHLCV) summarizes one interval: the opening, highest, lowest, and closing price, plus volume and trade count. Rows come back oldest first.

To fetch candles:

```bash theme={null}
$ curl -i -X GET \
  "https://YOUR_BASE_URL/v1/exchange/markets/USDT-NGN/candles?interval=1h&limit=2" \
  -H 'Authorization: Bearer YOUR_SECRET_TOKEN'
```

`interval` is required and is one of `1m`, `5m`, `15m`, `30m`, `1h`, `4h`, `1d`, or `1w`. `limit` defaults to `200` and is capped at `1000`.

**Expected Response:**

```json theme={null}
{
  "status": "success",
  "message": "Candles retrieved",
  "data": [
    {
      "time": "2026-10-06T13:00:00Z",
      "open": "1364.32",
      "high": "1364.32",
      "low": "1363.45",
      "close": "1363.45",
      "volume": "0.2",
      "quote_volume": "272.77",
      "trades": 2
    }
  ]
}
```

`time` is the instant the interval opened, so a `1h` candle covers `time` up to one hour after it. The bar that is still forming is included and moves as the market trades. There is no history ceiling — page back with `end_time`.

## Troubleshooting Common Issues

* **`not_found`:** The symbol does not exist. Symbols are `BASE-QUOTE` and uppercase (for example, `USDT-NGN`).

* **Invalid `depth`:** The value must be one of `1`, `5`, `10`, `20`, `50`, `100`, or `500`. Any other value is a validation error.

* **Empty `data: []`:** The market may be inactive or have no recent activity (for example, no trades in the window). Check the market's `status` with `GET /v1/exchange/markets/{symbol}`.

## What's Next?

Now that you can read market data, act on it:

* [Placing and Managing Orders](https://docs.busha.io/guides/exchange/orders.md)

* [Exchange Markets](https://docs.busha.io/guides/exchange/markets.md)


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