> 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/websocket-api/subscribe-and-unsubscribe/trade-subscribe.md).

# 实时成交明细（Trade）订阅

该 WebSocket 推送实时成交明细。

### 请求频率

同一连接所有请求（订阅、取消订阅、心跳）限制见 [WebSocket限制](/getting-started/api-limitation/websocket.md)（1 分钟 60 次）。超出将断连。

### 错误码说明

见 [WebSocket错误码](/getting-started/error-codes/websocket.md)。

### 接口地址

见 [行情地址说明](/getting-started/api-endpoints.md)。标的写法见 标的代码约定。

### 请求（协议号：10000）

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

| 参数名         | 类型      | 必填 | 描述                                                                    | 示例值                                |
| ----------- | ------- | -- | --------------------------------------------------------------------- | ---------------------------------- |
| `code`      | Integer | 是  | 实时成交订阅协议号                                                             | `10000`                            |
| `trace`     | String  | 是  | 可追溯 ID                                                                | `423afec425004bd8a5e02e1ba5f9b2b0` |
| `data`      | JSON    | 是  | 订阅数据                                                                  |                                    |
| `codes`     | String  | 是  | 逗号分隔；单连接与总数上限按套餐                                                      | `BTCUSDT`                          |
| `includeTy` | Boolean | 否  | `business=stock` 专用。布尔值 `true` 开启 `ty`，`false` 关闭；首次默认关闭，重复订阅省略则保留原设置 | `false`                            |

### 数字币合约的标记价、资金费率与持仓量

`business=crypto` 的成交订阅可在 `data` 内传入 `withMarkPrice: true`，让有相应数据的合约成交附带指数价、标记价、资金费率、下次结算时间、持仓量和持仓量时间。该参数与股票通道的 `includeTy` 独立；`crypto` 和 `common` 不返回股票成交类型 `ty`。

| 参数名                  | 类型      | 必填 | 描述                                                   |
| -------------------- | ------- | -- | ---------------------------------------------------- |
| `data.withMarkPrice` | Boolean | 否  | 仅 `business=crypto`。默认 `false`；`true` 时按数据可用性附带下表六字段 |

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

示例 `BTCUSDT.P` 为永续合约；选择其他产品时，请使用代码表返回的实际合约 `symbol`，保留其后缀和分隔符。适用于有标记价数据的数字币永续、股票永续、大宗和指数合约；现货与股票代币没有这六字段。

| 推送字段（位于 `data`） | 类型     | 必填 | 描述                                 |
| --------------- | ------ | -- | ---------------------------------- |
| `indexPx`       | String | 否  | 指数价格；十进制字符串                        |
| `markPx`        | String | 否  | 标记价格；十进制字符串                        |
| `fundRate`      | String | 否  | 最新资金费率小数值；例如 `"0.0001"` 表示 `0.01%` |
| `fundTime`      | Long   | 否  | 下次结算时间，Unix 毫秒时间戳                  |
| `openInt`       | String | 否  | 持仓量（Open interest）；保留原字符串精度        |
| `openIntTime`   | Long   | 否  | 持仓量采样时间，Unix 毫秒时间戳                 |

开启 `withMarkPrice` 且六字段都有数据时，推送示例为：

```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
    }
}
```

这些字段随 `10002` 成交消息发送，不是独立的定时推送。未开启时不返回这六字段；开启后，每个字段按数据可用性返回。`indexPx`、`markPx`、`fundRate`、`openInt` 为空或仅含空白时省略，字符串 `"0"` 会保留；`fundTime`、`openIntTime` 为 `0` 或负值时省略。持仓量来自最近可用快照，`openIntTime` 不一定与成交时间 `t` 相同。同一连接重新订阅某个代码时，`withMarkPrice` 按本次请求覆盖；省略或传 `false` 会关闭该代码的附加字段。取消成交订阅也会清除此设置。

订阅会追加到当前连接；成功应答不保证立刻产生行情快照。行情随数据更新推送，客户端应及时读取；慢速接收期间中间更新可能被合并。

### 应答（协议号：10001）

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

| 字段名     | 类型      | 必填 | 描述           | 示例值                                |
| ------- | ------- | -- | ------------ | ---------------------------------- |
| `code`  | Integer | 是  | 订阅应答协议号      | `10001`                            |
| `trace` | String  | 是  | 与请求一致        | `423afec425004bd8a5e02e1ba5f9b2b0` |
| `msg`   | String  | 是  | `ok` 只表示帧被收下 | `ok`                               |

`msg=ok` 只表示帧被收下。`business` 与品种市场不一致时仍可能 ack，但不推数据。

### 推送（协议号：10002）

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

| 字段名    | 类型      | 必填 | 描述                                  | 示例值             |
| ------ | ------- | -- | ----------------------------------- | --------------- |
| `code` | Integer | 是  | 实时成交推送协议号                           | `10002`         |
| `data` | JSON    | 是  | 成交数据                                |                 |
| `s`    | String  | 是  | 标的                                  | `BTCUSDT`       |
| `p`    | String  | 是  | 成交价                                 | `103482.94`     |
| `t`    | Long    | 是  | 成交时间戳（毫秒）                           | `1747552358393` |
| `td`   | Integer | 是  | 方向：`0` 默认，`1` 买，`2` 卖               | `2`             |
| `v`    | String  | 是  | 成交量                                 | `0.00096`       |
| `vw`   | String  | 是  | 成交额（不是均价）                           | `99.3436224`    |
| `ty`   | String  | 否  | 股票通道的交易所成交类型；仅 `includeTy=true` 时出现 |                 |

### 交易类型

#### 港股

* `*` 场外交易
* `D` 碎股交易
* `M` 非自动对盘
* `P` 开市前成交盘
* `U` 竞价交易
* `X` 同一券商非自动对盘
* `Y` 同一券商自动对盘
* （空）自动对盘

#### 美股

* （空）自动对盘
* `A` 收购
* `B` 批量交易
* `D` 分配
* `F` 跨市扫盘单
* `G` 批量卖出
* `H` 离价交易
* `I` 碎股交易
* `K` 纽交所规则 155
* `M` 交易所收盘价
* `P` 前参考价
* `Q` 交易所开盘价
* `S` 拆单交易
* `V` 附属交易
* `W` 平均价成交
* `X` 跨市场交易
* `1` 停售股票（常规交易）