> For the complete documentation index, see [llms.txt](https://docs.outpoll.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.outpoll.com/api/futures-api/rest-api/futures-market-data.md).

# Futures Market Data

Public REST snapshots of futures market data: candles, order book, recent trades, funding rates, 24h statistics.

Use these endpoints to load history and the current state once; then follow the [Futures Market Data streams](broken://pages/03869a2c7095ebee30a177ae823d7a4420086e38) for live updates.

## Service host

| Path prefix | Host                                             |
| ----------- | ------------------------------------------------ |
| `/api/v1/*` | `https://futures-marketdata-service.outpoll.com` |

## Authentication

No authentication required.

## Conventions

* **Pair ID** (`pairId`) is the `gid` from [Get Public Pairs](broken://pages/bba14d4639c3c29cf6fdbadc86ec5d4dfeea3b07#get-public-pairs).
* **Numbers** are decimals. Parse them as decimals, not floats (in Python: `response.json(parse_float=Decimal)`).
* **Time** is epoch **milliseconds**, UTC.
* **Server time**: every response carries the HTTP `Date` header (UTC, one-second precision). Use it to check your clock before signing private requests — the signature timestamp must be within ±30 seconds of server time.
* Unknown `pairId` → `404` with an empty body.

## Get Candles

Return historical OHLCV candles of one pair, oldest first.

```http
GET /api/v1/candles/history
```

* Paging:
  * no `from` / `to` → the latest `limit` candles;
  * `from` only → the first `limit` candles opening at or after `from` (page forward);
  * `to` only → the last `limit` candles opening at or before `to` (page back: pass the oldest loaded candle's `t` to get the previous page);
  * `from` and `to` → the first `limit` candles in the window.
* The last candle of the latest page may still be open and changing; follow [Candles](broken://pages/f0d22ed33d245974fe5372acba7dc6fa9f70a421) for live updates.
* An unsupported `interval` returns an empty `cs` array.

### Query Parameters

| Parameter | Type    | Required | Default | Description                                                                                                          |
| --------- | ------- | -------- | ------- | -------------------------------------------------------------------------------------------------------------------- |
| pairId    | integer | Yes      | —       | Pair ID                                                                                                              |
| interval  | string  | Yes      | —       | `1m`, `5m`, `15m`, `30m`, `1h`, `4h`, `6h`, `1d`, `1w` (opens Monday 00:00 UTC), `1mo` (opens on the 1st, 00:00 UTC) |
| from      | integer | No       | —       | Earliest candle open time, epoch ms, inclusive                                                                       |
| to        | integer | No       | —       | Latest candle open time, epoch ms, inclusive                                                                         |
| limit     | integer | No       | `500`   | Clamped to `1`–`1500`                                                                                                |

### Response `200 OK`

```json
{
  "pi": 1,
  "iv": "1h",
  "cs": [
    { "t": 1790852400000, "o": 83931.60000000, "h": 84018.30000000, "l": 83743.70000000, "c": 83882.20000000, "v": 1675.56528494 },
    { "t": 1790856000000, "o": 83882.30000000, "h": 84028.80000000, "l": 83691.10000000, "c": 83733.90000000, "v": 1520.81092372 }
  ]
}
```

| Field   | Type    | Description                                                  |
| ------- | ------- | ------------------------------------------------------------ |
| pi      | integer | Pair ID                                                      |
| iv      | string  | Interval                                                     |
| cs      | array   | Candles, oldest first                                        |
| cs\[].t | integer | Open time, epoch ms, UTC                                     |
| cs\[].o | number  | Open price                                                   |
| cs\[].h | number  | High price                                                   |
| cs\[].l | number  | Low price                                                    |
| cs\[].c | number  | Close price; the latest trade price while the candle is open |
| cs\[].v | number  | Volume in the base coin                                      |

## Get Order Book

Return a snapshot of the order book of one pair.

```http
GET /api/v1/book/depth
```

* Asks ascending from the best ask, bids descending from the best bid.
* With `group`, levels are placed on that price grid and their sizes aggregated. Omit it for the pair's tick size. More than 8 decimal places → `400`.
* To keep a local book, take this snapshot and apply [Order Book](broken://pages/bd7f0f3eccdcc07fd9c22c3867984fde6f1dcddc) stream updates on top of it.

### Query Parameters

| Parameter | Type    | Required | Default   | Description                                        |
| --------- | ------- | -------- | --------- | -------------------------------------------------- |
| pairId    | integer | Yes      | —         | Pair ID                                            |
| depth     | integer | No       | `20`      | Levels per side; larger values are capped at `100` |
| group     | number  | No       | tick size | Price grouping step, e.g. `0.1`, `1`, `10`         |

### Response `200 OK`

```json
{
  "pi": 1,
  "t": 1790859116848,
  "a": [ { "p": 83723.4, "v": 0.900 }, { "p": 83723.5, "v": 0.022 } ],
  "b": [ { "p": 83723.3, "v": 0.113 }, { "p": 83723.2, "v": 1.603 } ]
}
```

| Field           | Type    | Description                  |
| --------------- | ------- | ---------------------------- |
| pi              | integer | Pair ID                      |
| t               | integer | Snapshot time, epoch ms      |
| a               | array   | Asks, best (lowest) first    |
| b               | array   | Bids, best (highest) first   |
| a\[].p / b\[].p | number  | Price level                  |
| a\[].v / b\[].v | number  | Size at the level, base coin |

Errors with a body use the shape `{"error", "timestamp", "message"}`:

```json
{ "error": "bad_request", "timestamp": 1790859121994, "message": "group: at most 8 decimal places" }
```

## Get Recent Trades

Return the latest public trades of one pair, newest first.

```http
GET /api/v1/trades/recent
```

### Query Parameters

| Parameter | Type    | Required | Default | Description          |
| --------- | ------- | -------- | ------- | -------------------- |
| pairId    | integer | Yes      | —       | Pair ID              |
| limit     | integer | No       | `50`    | Clamped to `1`–`100` |

### Response `200 OK`

```json
{
  "pi": 1,
  "ts": [
    { "id": "t_408897288", "p": 83778.20000000, "v": 0.37200000, "s": "sell", "t": 1790859153012 },
    { "id": "t_408897286", "p": 83778.30000000, "v": 0.01000000, "s": "buy", "t": 1790859152352 }
  ]
}
```

| Field    | Type    | Description                                                                                                                                                                                                             |
| -------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| pi       | integer | Pair ID                                                                                                                                                                                                                 |
| ts       | array   | Trades, newest first                                                                                                                                                                                                    |
| ts\[].id | string  | Trade ID. Here every fill is listed separately; the [Trades](broken://pages/1133856d5d69c1582c8f9531d2e39a5612bb0f35) stream merges fills of one price and time into one frame, which carries the ID of its newest fill |
| ts\[].p  | number  | Trade price                                                                                                                                                                                                             |
| ts\[].v  | number  | Trade size, base coin                                                                                                                                                                                                   |
| ts\[].s  | string  | Taker side: `buy` or `sell`                                                                                                                                                                                             |
| ts\[].t  | integer | Trade time, epoch ms                                                                                                                                                                                                    |

## Get Funding Rates

Return the funding rate that will be applied at the next funding time, for one pair or all pairs.

```http
GET /api/v1/funding/rate
```

* Cached for 5 seconds. Follow [Funding](broken://pages/9a8f563cae88588be0dc555fd79815eb88c504a5) for live updates.

### Query Parameters

| Parameter | Type    | Required | Default | Description                 |
| --------- | ------- | -------- | ------- | --------------------------- |
| pairId    | integer | No       | —       | Pair ID; omit for all pairs |

### Response `200 OK`

```json
{
  "rs": [
    { "pi": 1, "nft": 1790870400000, "iv": 28800000, "elr": 0.00006178, "esr": -0.00006178 }
  ]
}
```

| Field     | Type    | Description                                                     |
| --------- | ------- | --------------------------------------------------------------- |
| rs        | array   | One item per pair                                               |
| rs\[].pi  | integer | Pair ID                                                         |
| rs\[].nft | integer | Next funding time, epoch ms, UTC                                |
| rs\[].iv  | integer | Funding interval in ms (`28800000` = 8 hours)                   |
| rs\[].elr | number  | Rate applied to long positions at `nft`; positive = longs pay   |
| rs\[].esr | number  | Rate applied to short positions at `nft`; positive = shorts pay |

## Get 24h Statistics

Return rolling 24-hour statistics of every pair.

```http
GET /api/v1/candles/lastDay
```

* A rolling window over the last 24 hours, not the UTC-day candle.
* Cached for 5 seconds. Follow [Ticker](broken://pages/03496c5fbfe2e45fb88a4860f12cdec7c8cb6318) for live updates.

### Response `200 OK`

```json
{
  "d": [
    { "pi": 1, "o": 85430.1, "h": 85696.2, "lo": 83107.7, "c": 83723.3, "v": 66333.56832841, "ch": -1706.8, "chp": -2.0000, "mon": true }
  ]
}
```

| Field    | Type           | Description                                                |
| -------- | -------------- | ---------------------------------------------------------- |
| d        | array          | One item per pair                                          |
| d\[].pi  | integer        | Pair ID                                                    |
| d\[].o   | number         | Price 24 hours ago                                         |
| d\[].h   | number \| null | 24h high; `null` if not known yet                          |
| d\[].lo  | number \| null | 24h low; `null` if not known yet                           |
| d\[].c   | number         | Last price                                                 |
| d\[].v   | number         | 24h volume, base coin                                      |
| d\[].ch  | number         | 24h change, `c − o`                                        |
| d\[].chp | number         | 24h change in percent; `-2.0000` = −2 %                    |
| d\[].mon | boolean        | `true` = market open now, `false` = trading session closed |

## Python Example

{% code title="futures\_market\_data\_rest.py" %}

```python
from decimal import Decimal

import requests

HOST = "https://futures-marketdata-service.outpoll.com"


def get(path, **params):
    resp = requests.get(HOST + path, params=params, timeout=10)
    resp.raise_for_status()
    return resp.json(parse_float=Decimal)


candles = get("/api/v1/candles/history", pairId=1, interval="1h", limit=24)["cs"]
book = get("/api/v1/book/depth", pairId=1, depth=5)
funding = get("/api/v1/funding/rate", pairId=1)["rs"][0]

print("last close:", candles[-1]["c"])
print("best bid / ask:", book["b"][0]["p"], "/", book["a"][0]["p"])
print("next funding:", funding["nft"], "long rate:", funding["elr"])
```

{% endcode %}

## Related Pages

* [Futures Market Data streams](broken://pages/03869a2c7095ebee30a177ae823d7a4420086e38) for live updates.
* [Market](broken://pages/bba14d4639c3c29cf6fdbadc86ec5d4dfeea3b07) for pair IDs, tick size and lot size.
* [Futures API](broken://pages/5af105514c769e54cdcc5c7c16de2848aa3aa267) for trading endpoints.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.outpoll.com/api/futures-api/rest-api/futures-market-data.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
