> 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/websockets/futures-market-data/candles.md).

# Candles

Real-time OHLCV candles for futures pairs.

Use this stream to keep a chart live: it pushes the current (open) candle as trades arrive and a final frame when a candle closes.

## Endpoint

```
wss://futures-marketdata-service.outpoll.com/ws/candles
```

## Authentication

No authentication required.

## Message Envelope

| Field | Type    | Description                                                                |
| ----- | ------- | -------------------------------------------------------------------------- |
| `pi`  | integer | Pair ID                                                                    |
| `iv`  | string  | Candle interval                                                            |
| `t`   | integer | Candle open time, epoch ms                                                 |
| `o`   | number  | Open price                                                                 |
| `h`   | number  | High price                                                                 |
| `lo`  | number  | Low price                                                                  |
| `c`   | number  | Close (latest) price                                                       |
| `v`   | number  | Volume                                                                     |
| `cl`  | boolean | `true` = candle is closed and final; `false` = candle is open and changing |

## Message Types

| Type                        | Direction       | Description                                                                                    |
| --------------------------- | --------------- | ---------------------------------------------------------------------------------------------- |
| `subscribe` / `unsubscribe` | Client → Server | Start or stop a pair at an interval                                                            |
| Candle                      | Server → Client | Open candle update (`cl: false`) or final candle (`cl: true`)                                  |
| Error                       | Server → Client | `{"er", "msg"}` — see [Errors](broken://pages/7b60c6363e2dcb27a5c7d2ef03222a2bd85342c5#errors) |
| `ping` / `pong`             | Both            | Plain-text keep-alive                                                                          |

## Subscribe

```json
{"act": "subscribe", "pi": 1, "iv": "15m"}
```

| Field       | Type            | Required | Description                                                           |
| ----------- | --------------- | -------- | --------------------------------------------------------------------- |
| `act`       | string          | Yes      | `subscribe`                                                           |
| `pi` / `ps` | integer / array | Yes      | Pair ID, or list of pair IDs; `iv` applies to every pair in the frame |
| `iv`        | string          | No       | Interval, default `1m`                                                |

Supported intervals (case-sensitive):

| `iv`  | Candle length                                 |
| ----- | --------------------------------------------- |
| `1m`  | 1 minute                                      |
| `5m`  | 5 minutes                                     |
| `15m` | 15 minutes                                    |
| `30m` | 30 minutes                                    |
| `1h`  | 1 hour                                        |
| `4h`  | 4 hours                                       |
| `6h`  | 6 hours                                       |
| `1d`  | 1 day                                         |
| `1w`  | 1 week, opens Monday 00:00 UTC                |
| `1mo` | 1 calendar month, opens on the 1st, 00:00 UTC |

{% hint style="warning" %}
Any other `iv` value is accepted but delivers no frames — check the value before subscribing.
{% endhint %}

* One connection follows **one interval per pair**. Subscribing again to the same pair with a different `iv` switches the interval. To watch several intervals of one pair, open one connection per interval.
* `all: true` is not supported on this stream; subscribe by pair ID.

Server confirmation: there is no confirmation frame. Right after subscribing you receive the pair's most recent candle at that interval (sent with `cl: false`). Live updates follow.

## Candle Lifecycle

* All candle boundaries are UTC. `t` is the open time of the candle (inclusive).
* While a candle is open, frames with `cl: false` carry its running values. Updates are throttled, so not every trade produces a frame.
* When the first trade of the next period arrives, the server sends the finished candle once with `cl: true`, then the new candle with `cl: false`.
* Match frames to your chart by `t`: a frame with an existing `t` replaces that candle, a new `t` starts a new one.
* On a pair with no trades, a candle stays open on the stream until the next trade; use the time to decide that a period has ended.
* For history, load candles over REST and then apply this stream on top.

## Candle Payload

```json
{
  "pi": 1,
  "iv": "15m",
  "t": 1790661600000,
  "o": 64180.2,
  "h": 64297.0,
  "lo": 64151.8,
  "c": 64250.5,
  "v": 182.437,
  "cl": false
}
```

| Field | Type    | Description                                     |
| ----- | ------- | ----------------------------------------------- |
| `pi`  | integer | Pair ID                                         |
| `iv`  | string  | Interval                                        |
| `t`   | integer | Open time, epoch ms, UTC                        |
| `o`   | number  | Open price                                      |
| `h`   | number  | High price                                      |
| `lo`  | number  | Low price                                       |
| `c`   | number  | Close price; while open, the latest trade price |
| `v`   | number  | Volume in the base coin                         |
| `cl`  | boolean | `true` = final, `false` = open                  |

## Python Example

{% code title="candles.py" %}

```python
import asyncio
import json
from decimal import Decimal

import websockets

URL = "wss://futures-marketdata-service.outpoll.com/ws/candles"


async def main():
    candles = {}  # open time -> candle
    async with websockets.connect(URL) as ws:
        await ws.send(json.dumps({"act": "subscribe", "pi": 1, "iv": "1m"}))
        async for raw in ws:
            if raw == "pong":
                continue
            msg = json.loads(raw, parse_float=Decimal)
            if "er" in msg:
                print("error:", msg)
                continue
            candles[msg["t"]] = msg
            state = "closed" if msg["cl"] else "open"
            print(f"{msg['t']} {state}: O {msg['o']} H {msg['h']} "
                  f"L {msg['lo']} C {msg['c']} V {msg['v']}")


asyncio.run(main())
```

{% endcode %}


---

# 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/websockets/futures-market-data/candles.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.
