> For the complete documentation index, see [llms.txt](https://docs.infoway.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.infoway.io/en-docs/websocket/websocket-subscribe-method/candlestick-subscription.md).

# Candlestick Subscription

Learn how to subscribe to real-time candlestick (OHLCV) data via WebSocket.

### Overview

This page provides detailed documentation on how to subscribe to real-time candlestick (OHLCV) data using the WebSocket API. This WebSocket connection delivers continuous, live datafeeds for candlestick data across multiple markets such as stocks, cryptocurrencies, forex, and futures.

### **Request Frequency**

For a single WebSocket connection, all requests (subscribe, unsubscribe, heartbeat) are limited to 60 times per minute. If the request frequency limit is exceeded, the connection will be automatically closed. If disconnections occur too frequently, and the system deems them to be malicious requests, the API key will be banned. Please be mindful of the calling logic during usage.

### **Error Code Explanation**

Please refer to the [WebSocket error code](https://docs.infoway.io/en-docs/getting-started/error-codes/websocket-error-codes.md) documentation for further details.

### **Subscription Address**

Please refer to the [WebSocket subscription addresses.](https://docs.infoway.io/en-docs/websocket/subscription-address.md)

### **Request Quantity**

Different subscription plans allow varying numbers of products per WebSocket subscription. Please refer to the [WebSocket restrictions](https://docs.infoway.io/en-docs/getting-started/api-limitation/websocket-limitation.md) documentation for specific details.

### Request (Protocol Number: 10006)

```json
{
    "code": 10006,
    "trace": "423afec425004bd8a5e02e1ba5f9b2b0",
    "data": {
        "arr": [
            {
                "type": 1,
                "codes": "BTCUSDT,DOGUSDT"
            }
        ]
    }
}
```

| Parameter | Type    | Required | Description                                                                                                                                                                                                                                                                                                                                                                                                | Example                            |
| --------- | ------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------- |
| `code`    | Integer | Yes      | Request protocol number                                                                                                                                                                                                                                                                                                                                                                                    | `10006`                            |
| `trace`   | String  | Yes      | Traceable ID (random string)                                                                                                                                                                                                                                                                                                                                                                               | `423afec425004bd8a5e02e1ba5f9b2b0` |
| `data`    | JSON    | Yes      | Subscription data                                                                                                                                                                                                                                                                                                                                                                                          |                                    |
| `arr`     | Array   | Yes      | Multiple subscription entities                                                                                                                                                                                                                                                                                                                                                                             |                                    |
| `type`    | Integer | Yes      | <p>The type of candlestick interval. Options:<br><code>1</code> = 1 minute<br><code>2</code> = 5 minutes<br><code>3</code> = 15 minutes<br><code>4</code> = 30 minutes<br><code>5</code> = 1 hour<br><code>6</code> = 2 hours<br><code>7</code> = 4 hours<br><code>8</code> = 1 day<br><code>9</code> = 1 week<br><code>10</code> = 1 month<br><code>11</code> = 1 quarter<br><code>12</code> = 1 year</p> | `1`                                |
| `codes`   | String  | Yes      | Product symbols (comma-separated for multiple). India / Japan may use `BSE:INFY.IN` on `arr[].codes`                                                                                                                                                                                                                                                                                                       | `BTCUSDT`                          |

### Response (Protocol Number: 10007)

```
{
    "code": 10007,
    "trace": "423afec425004bd8a5e02e1ba5f9b2b0",
    "msg": "ok"
}
```

| Parameter | Type    | Required | Description                   | Example Value                      |
| --------- | ------- | -------- | ----------------------------- | ---------------------------------- |
| `code`    | Integer | Yes      | Response protocol number      | `10007`                            |
| `trace`   | String  | Yes      | Trace ID (same as in request) | `423afec425004bd8a5e02e1ba5f9b2b0` |
| `msg`     | String  | Yes      | Response message              | `ok`                               |

### Push (Protocol Number: 10008)

```
{
    "code": 10008,
    "data": {
        "c": "103478.27",
        "h": "103478.27",
        "l": "103478.26",
        "o": "103478.26",
        "pca": "0.00",
        "pfr": "0.00%",
        "s": "BTCUSDT",
        "t": "1747550640",
        "ty": 1,
        "v": "0.34716",
        "vw": "35923.5149678"
    }
}
```

| Parameter | Type    | Required | Description                                   | Example Value   |
| --------- | ------- | -------- | --------------------------------------------- | --------------- |
| `code`    | Integer | Yes      | Candlestick push protocol number              | `10008`         |
| `data`    | JSON    | Yes      | Kline push entity                             | —               |
| `s`       | String  | Yes      | Symbol name                                   | `BTCUSDT`       |
| `c`       | String  | Yes      | Closing price                                 | `103478.27`     |
| `h`       | String  | Yes      | Highest price                                 | `103478.27`     |
| `l`       | String  | Yes      | Lowest price                                  | `103478.26`     |
| `o`       | String  | Yes      | Opening price                                 | `103478.26`     |
| `pca`     | String  | Yes      | Price change amount                           | `0.00`          |
| `pfr`     | String  | Yes      | Price change percentage                       | `0.00%`         |
| `t`       | String  | Yes      | Kline time (Unix seconds as a decimal string) | `1747550640`    |
| `ty`      | Integer | Yes      | Kline type (refer to request parameter)       | `1`             |
| `v`       | String  | Yes      | Trade volume                                  | `0.34716`       |
| `vw`      | String  | Yes      | Trade value                                   | `35923.5149678` |

The request interval field is `data.arr[].type`; the push field is `data.ty`. `data.t` is a decimal string containing Unix seconds, whereas trade and depth timestamps are millisecond integers.

For `business=india` / `business=japan`, write the venue in `codes` (India `NSE:INFY.IN`/`BSE:INFY.IN`, Japan `TSE:7203.JP`/`SAPSE:7203.JP`/`NAG:7203.JP`/`FSE:7203.JP`). If omitted, one venue is resolved from the product list and the other venues for that symbol are dropped. An invalid prefix returns `506` with `msg` set to the prefix; an empty prefix or symbol uses `codes`. If any code in this subscribe has a prefix, pushes include `ex`. To receive more than one venue, send prefixed codes. See [Symbol convention](https://docs.infoway.io/en-docs/getting-started/symbol-convention.md). Put the venue prefix on `arr[].codes`. Do not send a separate `ex` field. Push field `data.ex` appears when this subscribe included a venue prefix.

The same candle can receive multiple updates. Update existing records by `s`, `ty`, and `t`. Pushes have no separate candle-closed flag. Subscriptions are added to the existing set; after the acknowledgement, wait for market updates. Use the HTTP API for historical data.
