> 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/latest-trade-subscription.md).

# Latest Trade Subscription

Real-time trade ticks over WebSocket.

### Overview

Subscribe to continuous trade updates (price, size, direction, timestamp) for equities, crypto, forex, and futures.

`includeTy` is an equity option for `business=stock`; use the exact field name. Crypto contracts have a separate `withMarkPrice` option described below.

### Request frequency

Each connection allows 60 frames per minute in total (subscribe, unsubscribe, heartbeat). See [WebSocket Limitation](https://docs.infoway.io/en-docs/getting-started/api-limitation/websocket-limitation.md). Exceeding the limit closes the socket. Repeated abuse may ban the API key.

### Error codes

See [WebSocket Error Codes](https://docs.infoway.io/en-docs/getting-started/error-codes/websocket-error-codes.md).

### Subscription address

See [Endpoints](https://docs.infoway.io/en-docs/getting-started/endpoints.md).

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).

### Request (protocol 10000)

```json
{
    "code": 10000,
    "trace": "423afec425004bd8a5e02e1ba5f9b2b0",
    "data": {
        "codes": "BTCUSDT"
    }
}
```

| Parameter   | Type    | Required | Description                                                                                                                                              | Example                            |
| ----------- | ------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------- |
| `code`      | Integer | Yes      | Subscribe protocol                                                                                                                                       | `10000`                            |
| `trace`     | String  | Yes      | Trace id                                                                                                                                                 | `423afec425004bd8a5e02e1ba5f9b2b0` |
| `data`      | JSON    | Yes      | Subscription body                                                                                                                                        |                                    |
| `codes`     | String  | Yes      | Comma-separated symbols; per-connection and total caps depend on your plan. India / Japan may use `BSE:INFY.IN`                                          | `BTCUSDT`                          |
| `includeTy` | Boolean | No       | `business=stock` only. Boolean `true` enables `ty`, `false` disables it. Initially off; omission on a repeat subscription preserves the existing setting | `false`                            |

### Mark prices, funding rates, and open interest for crypto contracts

For `business=crypto`, set `data.withMarkPrice` to `true` to include available index price, mark price, funding rate, next funding time, open interest, and open interest time in trade updates. This is independent of the equity-only `includeTy` option. The `crypto` and `common` channels do not return the equity trade-type field `ty`.

| Parameter            | Type    | Required | Description                                                                                      |
| -------------------- | ------- | -------- | ------------------------------------------------------------------------------------------------ |
| `data.withMarkPrice` | Boolean | No       | `business=crypto` only. Defaults to `false`; `true` includes the six fields below when available |

```json
{
    "code": 10000,
    "trace": "mark-price-1",
    "data": {
        "codes": "BTCUSDT.P",
        "withMarkPrice": true
    }
}
```

The example `BTCUSDT.P` is a perpetual contract. For other products, use the exact contract `symbol` returned by the symbol list, preserving its suffix and separators. The option applies to crypto perpetuals, stock perpetuals, commodity contracts, and index contracts with mark-price data. Spot assets and stock tokens do not have these fields.

| Push field (inside `data`) | Type   | Required | Description                                                     |
| -------------------------- | ------ | -------- | --------------------------------------------------------------- |
| `indexPx`                  | String | No       | Index price as a decimal string                                 |
| `markPx`                   | String | No       | Mark price as a decimal string                                  |
| `fundRate`                 | String | No       | Latest funding rate as a decimal; `"0.0001"` means `0.01%`      |
| `fundTime`                 | Long   | No       | Next funding time as a Unix timestamp in milliseconds           |
| `openInt`                  | String | No       | Open interest; preserves the original string precision          |
| `openIntTime`              | Long   | No       | Open interest snapshot time as a Unix timestamp in milliseconds |

Example push with `withMarkPrice` enabled and all six fields available:

```json
{
    "code": 10002,
    "data": {
        "p": "103482.94",
        "s": "BTCUSDT.P",
        "t": 1791957736000,
        "td": 2,
        "v": "0.00096",
        "vw": "99.3436224",
        "indexPx": "103470.00",
        "markPx": "103480.00",
        "fundRate": "0.0001",
        "fundTime": 1791993600000,
        "openInt": "91968.102",
        "openIntTime": 1791957735679
    }
}
```

These fields accompany `10002` trade messages; they are not an independent periodic feed. All six fields are omitted when the option is disabled. When enabled, each field is returned only if available. Empty or whitespace-only `indexPx`, `markPx`, `fundRate`, and `openInt` values are omitted, while the string `"0"` is preserved. `fundTime` and `openIntTime` are omitted when zero or negative. Open interest comes from the latest available snapshot, so `openIntTime` may differ from the trade timestamp `t`. Resubscribing a symbol on the same connection replaces its `withMarkPrice` setting: omission or `false` disables the extra fields for that symbol. Unsubscribing clears the setting.

Subscriptions are added to the connection's existing set. A successful acknowledgement does not guarantee an immediate snapshot. Updates arrive as market data changes; consume them promptly, as intermediate updates can be combined for slow receivers.

### Response (protocol 10001)

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

`msg=ok` only means the frame was accepted. A `business` that does not match the symbol market can still ack and then never push.

| Parameter | Type    | Required | Description               | Example                            |
| --------- | ------- | -------- | ------------------------- | ---------------------------------- |
| `code`    | Integer | Yes      | Ack protocol              | `10001`                            |
| `trace`   | String  | Yes      | Echo of the request trace | `423afec425004bd8a5e02e1ba5f9b2b0` |
| `msg`     | String  | Yes      | `ok`                      | `ok`                               |

### Push (protocol 10002)

```json
{
    "code": 10002,
    "data": {
        "p": "103482.94",
        "s": "BTCUSDT",
        "t": 1747552358393,
        "td": 2,
        "v": "0.00096",
        "vw": "99.3436224"
    }
}
```

| Parameter | Type    | Required | Description                                                               | Example         |
| --------- | ------- | -------- | ------------------------------------------------------------------------- | --------------- |
| `code`    | Integer | Yes      | Push protocol                                                             | `10002`         |
| `data`    | JSON    | Yes      | Tick                                                                      |                 |
| `s`       | String  | Yes      | Symbol                                                                    | `BTCUSDT`       |
| `p`       | String  | Yes      | Price                                                                     | `103482.94`     |
| `t`       | Long    | Yes      | Trade timestamp (milliseconds)                                            | `1747552358393` |
| `td`      | Integer | Yes      | `0` default, `1` buy, `2` sell                                            | `2`             |
| `v`       | String  | Yes      | Volume                                                                    | `0.00096`       |
| `vw`      | String  | Yes      | **Turnover / trade value** (not VWAP)                                     | `99.3436224`    |
| `ty`      | String  | No       | Equity-channel exchange trade type; only when `includeTy` is `true`       |                 |
| `ex`      | String  | No       | India and Japan only. Present when this subscribe included a venue prefix | `NSE`           |

### Transaction types

#### Hong Kong

* `*` Off-exchange
* `D` Odd lot
* `M` Non-automatic matching
* `P` Pre-market matching
* `U` Auction
* `X` Same-broker non-automatic
* `Y` Same-broker automatic
* (blank) Automatic matching

#### US

* (blank) Automatic matching
* `A` Acquisition
* `B` Block
* `D` Allocation
* `F` Intermarket sweep
* `G` Block sell
* `H` Away-from-market
* `I` Odd lot
* `K` NYSE Rule 155
* `M` Exchange close
* `P` Prior reference
* `Q` Exchange open
* `S` Split
* `V` Contingent
* `W` Average price
* `X` Cross-market
* `1` Restricted stock (regular hours)
