概览OKX.AI钱包支付交易行情Exchange OSX Layer
開發者平臺
主題
概览
介绍
用户引导
链网络与基础设施
交易场所
支持市場
产品核心概念
账户
市场与交易产品
价格
订单与交易
保证金、清算与风险
费用
Open API
快速开始
API 参考
WebSocket
公有WebSocket
私有WebSocket
SDK
错误码
支持
Open API

公有WebSocket通用规范#

连接地址#

环境公共频道地址
Productionwss://{public-host}/ws/v5/public

公共频道无需登录。

连接与心跳规则#

每个 IP 地址每秒最多建立 3 次 WebSocket 连接。

WebSocket 操作请求限流#

WebSocket 操作请求采用令牌桶机制，限流维度为单个 WebSocket 连接，即单个 Netty Channel。

规则限制
限流维度单个 WebSocket 连接
令牌桶容量480 个 token
连接建立时的初始令牌480 个 token
令牌恢复速度每小时 480 个，约每 7.5 秒恢复 1 个
单次请求消耗1 个 token
纳入限流的请求login、subscribe、unsubscribe 等客户端操作请求
是否按频道分开计算否，同一连接上的所有频道共享同一个令牌桶
是否按 IP 共享否，同一 IP 建立的不同连接各自拥有独立令牌桶
重新连接连接断开并重新建立后，新连接获得一个初始满载的 480 token 令牌桶

一次完整的 WebSocket 操作请求消耗 1 个 token。当一次 subscribe 或 unsubscribe 请求的 args[] 中包含多个频道或产品时，仍视为一条请求，只消耗 1 个 token。

令牌以每小时 480 个的速度持续恢复，令牌桶上限为 480；令牌不会在每小时整点重置。因此，单个连接建立后最多可以突发发送 480 条操作请求，之后约每 7.5 秒恢复一个 token。

同一连接上的所有 subscribe 和 unsubscribe 操作共享同一个令牌桶，不会按照 tickers、trades 等业务频道分别计算。

空闲断线与心跳#

连接成功后 30 秒内未订阅，或订阅后服务器连续 30 秒未推送数据，系统会自动断开连接。

客户端每次收到消息后，应设置一个小于 30 秒的定时器。如果定时器触发前未收到新消息，客户端应发送文本字符串 ping，并等待服务器返回文本字符串 pong。如果未在预期时间内收到 pong，客户端应报告错误或重新建立连接。

数据类型约定#

所有参数仅使用三种数据类型：

  • String：绝大多数参数使用此类型。
  • Boolean：布尔值。
  • Integer：仅用于序列号等例外场景。

所有数值，包括价格、数量和时间戳，均以 String 返回。时间戳统一使用 Unix epoch 毫秒，并以 String 表示。

数值不使用科学计数法，例如使用 0.000001，而不是 1E-6。小数不保留无意义的尾随零，例如使用 5，而不是 5.0。

订阅（subscribe）#

请求格式

json
{
  "id": "1512",
  "op": "subscribe",
  "args": [
    {
      "channel": "exchangeos-tickers",
      "assetId": "1"
    }
  ]
}

一次请求可以订阅一个或多个频道。args 中的频道对象总大小不得超过 64 KB。

请求参数

参数类型是否必填说明
idString否消息唯一标识，与 V5 对齐。由用户提供，服务器在响应中原样返回以匹配请求。仅支持字母和数字，长度为 1–32 个字符。
opString是操作类型，固定为 subscribe。
argsArray of Objects是要订阅的频道列表。
> channelString是频道名称。
> assetIdString否产品 ID。

成功返回示例

json
{
  "event": "subscribe",
  "arg": {
    "channel": "exchangeos-tickers",
    "assetId": "1234"
  },
  "connId": "accb8e21"
}

返回参数

参数类型是否必填说明
eventString是事件类型，可以是 subscribe 或 error。
argObject否订阅的频道信息。
> channelString是频道名称。
> assetIdString否产品 ID。
codeString否请求失败时返回的错误码。
msgString否请求失败时返回的错误消息。
connIdString是WebSocket 连接 ID。

取消订阅（unsubscribe）#

请求示例

json
{
  "op": "unsubscribe",
  "args": [
    {
      "channel": "exchangeos-tickers",
      "assetId": "1234"
    }
  ]
}

请求参数

参数类型是否必填说明
opString是操作类型，固定为 unsubscribe。
argsArray of Objects是要取消订阅的频道列表。
> channelString是频道名称。
> assetIdString否产品 ID。

返回示例

json
{
  "event": "unsubscribe",
  "arg": {
    "channel": "exchangeos-tickers",
    "assetId": "1234"
  },
  "connId": "d0b44253"
}

返回参数

参数类型是否必填说明
eventString是事件类型，可以是 unsubscribe 或 error。
argObject否取消订阅的频道信息。
> channelString是频道名称。
> assetIdString否产品 ID。
codeString否错误码。
msgString否错误消息。
connIdString是WebSocket 连接 ID。

通知消息（event = notice）#

服务升级前约 60 秒，服务器会推送通知消息，提示客户端重新建立连接。

json
{
  "event": "notice",
  "code": "64008",
  "msg": "The connection will soon be closed for a service upgrade. Please reconnect.",
  "connId": "a4d3ae55"
}

行情频道 exchangeos-tickers#

推送单个 spot 或 perp 产品的最新成交、最优买卖盘及 24 小时行情；字段变更时推送。

json
{
  "op": "subscribe",
  "args": [
    {
      "channel": "exchangeos-tickers",
      "assetId": "1234"
    }
  ]
}
字段类型说明
assetIdString产品资产 ID。
lastPxString最新成交价。
lastPxUsdString最新成交价的 USD 估值；无法计算时返回空字符串。
lastSzString最新成交数量。
askPx / askSzString最优卖价与最优卖量。
bidPx / bidSzString最优买价与最优买量。
open24hString24 小时开盘价。
high24h / low24hString24 小时最高价与最低价。
vol24hString24 小时成交量。
volCcy24hString24 小时成交额。
sodUtc0 / sodUtc8StringUTC+0 / UTC+8 当日开盘价。
tsString推送时间，Unix epoch 毫秒。
json
{
  "arg": {
    "channel": "exchangeos-tickers",
    "assetId": "1234"
  },
  "data": [
    {
      "assetId": "1234",
      "lastPx": "97520.5",
      "lastPxUsd": "97320.5",
      "lastSz": "0.0012",
      "askPx": "97521",
      "askSz": "1.5234",
      "bidPx": "97520",
      "bidSz": "2.3041",
      "open24h": "96800",
      "high24h": "98100.3",
      "low24h": "96210.5",
      "volCcy24h": "582310412.56",
      "vol24h": "5980.23",
      "sodUtc0": "96950",
      "sodUtc8": "97010.2",
      "ts": "1710249600000"
    }
  ]
}

成交频道 exchangeos-trades#

推送指定产品的最近成交。服务端最多每 100 ms 推送一次，每个聚合段最多 20 笔原始成交。只有区块、assetId、价格、方向相同且成交 ID 连续的成交才会被聚合。

json
{
  "op": "subscribe",
  "args": [
    {
      "channel": "exchangeos-trades",
      "assetId": "1234"
    }
  ]
}
字段类型说明
assetIdString产品资产 ID。
fIdString聚合段第一笔成交 ID。
lIdString聚合段最后一笔成交 ID。
pxString成交价格。
szString聚合后的成交数量。
sideString主动成交方向：buy 或 sell。
tsString推送时间，Unix epoch 毫秒。
json
{
  "arg": {
    "channel": "exchangeos-trades",
    "assetId": "2"
  },
  "data": [
    {
      "assetId": "2",
      "fId": "1512",
      "lId": "1512",
      "px": "1",
      "sz": "10",
      "side": "buy",
      "ts": "1785516597767"
    }
  ]
}

成交 K 线频道 exchangeos-candle{bar}#

推送成交 K 线，数据变更时推送。将 {bar} 替换为实际粒度。

支持粒度：1m、5m、15m、1H、4H、1D。预测市场整合场景还可能支持 3m、30m、2H、6H、12H、1W、1M，以实际开通的粒度为准。

json
{
  "op": "subscribe",
  "args": [
    {
      "channel": "exchangeos-candle1H",
      "assetId": "1234"
    }
  ]
}

data[] 的每个元素为固定长度的 9 元素字符串数组：

索引字段说明
0tsK 线开始时间，Unix epoch 毫秒。
1open开盘价。
2high最高价。
3low最低价。
4close收盘价。
5vol成交量。
6volCcy成交量币种口径数据。
7volCcyQuote计价币种成交额口径数据。
8confirm0：未完结；1：已完结。
json
{
  "arg": {
    "channel": "exchangeos-candle1H",
    "assetId": "1234"
  },
  "data": [
    [
      "1710000000000",
      "50000",
      "51000",
      "49500",
      "50500",
      "1234.5",
      "617250000",
      "617250000",
      "0"
    ]
  ]
}

标记价格 K 线频道 exchangeos-mark-price-candle{bar}#

推送指定产品的标记价格 K 线，不包含成交量或成交额。

支持粒度：1s、1m、5m、15m、1H、4H、1D。

json
{
  "op": "subscribe",
  "args": [
    {
      "channel": "exchangeos-mark-price-candle1s",
      "assetId": "2"
    }
  ]
}

data[] 的每个元素为：

索引字段说明
0tsK 线开始时间，Unix epoch 毫秒。
1open开盘标记价格。
2high最高标记价格。
3low最低标记价格。
4close当前或最终收盘标记价格。
5confirm0：未完结；1：已完结。

未完结 K 线会重复推送。客户端应以 channel + assetId + ts 作为唯一键，并以最新数据覆盖旧数据。

json
{
  "arg": {
    "channel": "exchangeos-mark-price-candle1s",
    "assetId": "2"
  },
  "data": [
    [
      "1785912897000",
      "1.0298",
      "1.0298",
      "1.0298",
      "1.0298",
      "0"
    ]
  ]
}

指数行情频道 exchangeos-index-tickers#

推送指数最新价格与 24 小时统计。价格发生变化时最快每秒推送一次；无变化时每分钟至少推送一次。

json
{
  "op": "subscribe",
  "args": [
    {
      "channel": "exchangeos-index-tickers",
      "assetId": "1234"
    }
  ]
}
字段类型说明
assetIdString指数对应的资产 ID。
idxPxString最新指数价格。
open24hString24 小时开盘价。
high24h / low24hString24 小时最高价与最低价。
sodUtc0 / sodUtc8StringUTC+0 / UTC+8 当日开盘价。
tsString推送时间，Unix epoch 毫秒。
json
{
  "arg": {
    "channel": "exchangeos-index-tickers",
    "assetId": "1234"
  },
  "data": [
    {
      "assetId": "1234",
      "idxPx": "64972.1",
      "high24h": "65500",
      "low24h": "64200",
      "open24h": "64800",
      "sodUtc0": "64900",
      "sodUtc8": "64950",
      "ts": "1781701360808"
    }
  ]
}

指数 K 线频道 exchangeos-index-candle{bar}#

推送指数 OHLC K 线，不包含成交量。

支持粒度：1m、5m、15m、1H、4H、1D。

json
{
  "op": "subscribe",
  "args": [
    {
      "channel": "exchangeos-index-candle1H",
      "assetId": "1234"
    }
  ]
}

data[] 的每个元素为 [ts, open, high, low, close, confirm]。

json
{
  "arg": {
    "channel": "exchangeos-index-candle1H",
    "assetId": "1234"
  },
  "data": [
    [
      "1710000000000",
      "50000",
      "51000",
      "49500",
      "50500",
      "0"
    ]
  ]
}

资金费率频道 exchangeos-funding-rate#

推送永续合约当前预测资金费率及下一次结算信息，默认每 5 秒推送一次。该频道不返回 fundingTime；如需查询该字段，请使用 REST GET /market/funding-rate。

json
{
  "op": "subscribe",
  "args": [
    {
      "channel": "exchangeos-funding-rate",
      "assetId": "2"
    }
  ]
}
字段类型说明
assetIdString永续合约资产 ID。
fundingRateString当前预测资金费率。
nextFundingTimeString下一次结算时间，Unix epoch 毫秒。
settlementIntervalString结算周期。
minFundingRate / maxFundingRateString资金费率下限与上限。
fundingSwitchBoolean是否启用资金费率。
json
{
  "arg": {
    "channel": "exchangeos-funding-rate",
    "assetId": "2"
  },
  "data": [
    {
      "assetId": "2",
      "fundingRate": "-0.0042",
      "nextFundingTime": "1785916800000",
      "settlementInterval": "1",
      "minFundingRate": "-0.015",
      "maxFundingRate": "0.015",
      "fundingSwitch": true
    }
  ]
}

产品频道 exchangeos-instruments#

按产品类型批量订阅。首次与任意产品参数变化时，服务端推送该 instType 的完整产品列表。支持 spot 与 perp，不支持预测市场产品线。

触发场景包括：产品状态变化、priceDecimals 或 sizeDecimals 变更、listTime 或 expTime 变更。产品正式下架前约 30 分钟会推送变更。

json
{
  "op": "subscribe",
  "args": [
    {
      "channel": "exchangeos-instruments",
      "instType": "perp"
    }
  ]
}
字段类型说明
instTypeStringspot 或 perp。
assetIdString产品资产 ID。
settleTokenIdString结算币种 ID；spot 可能为空字符串。
priceDecimalsString价格精度位数。
sizeDecimalsString数量精度位数。
stateString产品状态，例如 live。
listTimeString上线时间，Unix epoch 毫秒。
expTimeString下线或到期时间；无值时为空字符串。
upcChgArray待生效的参数变更列表。
upcChg[].paramStringpriceDecimals 或 sizeDecimals。
upcChg[].newValueString生效后的新值。
upcChg[].effTimeString参数生效时间，Unix epoch 毫秒。
tsString推送时间，Unix epoch 毫秒。

参数变更会经历两个阶段：预告期中顶层字段仍是旧值，upcChg 提供新值和生效时间；生效后顶层字段变为新值，upcChg 为空数组。

json
{
  "arg": {
    "channel": "exchangeos-instruments",
    "instType": "perp"
  },
  "data": [
    {
      "instType": "perp",
      "assetId": "5678",
      "settleTokenId": "0",
      "priceDecimals": "1",
      "sizeDecimals": "3",
      "state": "live",
      "listTime": "1710000000000",
      "expTime": "",
      "upcChg": [
        {
          "param": "priceDecimals",
          "newValue": "2",
          "effTime": "1710086400000"
        }
      ],
      "ts": "1710000000000"
    }
  ]
}

持仓总量频道 exchangeos-open-interest#

推送永续合约持仓总量；有更新时每 3 秒推送一次。

json
{
  "op": "subscribe",
  "args": [
    {
      "channel": "exchangeos-open-interest",
      "assetId": "1234"
    }
  ]
}
字段类型说明
assetIdString永续合约资产 ID。
oiCcyString持仓量。
oiUsdString持仓量的 USD 估值。
tsString推送时间，Unix epoch 毫秒。
json
{
  "arg": {
    "channel": "exchangeos-open-interest",
    "assetId": "1234"
  },
  "data": [
    {
      "assetId": "1234",
      "oiCcy": "22161.13",
      "oiUsd": "1939251795.54",
      "ts": "1710249600000"
    }
  ]
}

限价频道 exchangeos-price-limit#

推送产品的最高买价 buyLmt 与最低卖价 sellLmt。无首推；限价带发生变化时最快每秒推送一次，无变化时不推送。首次配置 price band 会触发推送。没有有效限价带时，相关字段返回空字符串，而非 "0"。

json
{
  "op": "subscribe",
  "args": [
    {
      "channel": "exchangeos-price-limit",
      "assetId": "1234"
    }
  ]
}
字段类型说明
assetIdString产品资产 ID。
buyLmtString允许的最高买入限价；无值时为空字符串。
sellLmtString允许的最低卖出限价；无值时为空字符串。
tsString推送时间，Unix epoch 毫秒。
json
{
  "arg": {
    "channel": "exchangeos-price-limit",
    "assetId": "1234"
  },
  "data": [
    {
      "assetId": "1234",
      "buyLmt": "52000",
      "sellLmt": "48000",
      "ts": "1710249600000"
    }
  ]
}

深度频道#

exchangeos-books#

完整订单簿频道。首次推送完整快照 action: "snapshot"，后续推送增量 action: "update"。

json
{
  "op": "subscribe",
  "args": [
    {
      "channel": "exchangeos-books",
      "assetId": "1234"
    }
  ]
}

每个档位为 [price, size, orderCount]。增量消息中 size: "0" 表示删除该价格档位。

字段类型说明
asks / bidsArray卖盘或买盘档位列表。
tsString推送时间，Unix epoch 毫秒。
prevSeqIdInteger上一序列号。
seqIdInteger当前序列号。

客户端必须校验序列连续性：第一条 update 的 prevSeqId 必须等于快照 seqId；之后每条 update.prevSeqId 必须等于上一条 seqId。不连续时应重新订阅。60 秒无变化时，服务端可能发送 seqId == prevSeqId 的心跳帧。

json
{
  "arg": {
    "channel": "exchangeos-books",
    "assetId": "1234"
  },
  "action": "update",
  "data": [
    {
      "asks": [
        ["8477", "415", "3"]
      ],
      "bids": [
        ["8476", "0", "0"]
      ],
      "ts": "1710249600000",
      "prevSeqId": 123455,
      "seqId": 123456
    }
  ]
}

exchangeos-books5#

推送前 5 档完整订单簿快照。盘口变化时推送，不具有增量语义，无需序列校验。

json
{
  "op": "subscribe",
  "args": [
    {
      "channel": "exchangeos-books5",
      "assetId": "1234"
    }
  ]
}
json
{
  "arg": {
    "channel": "exchangeos-books5",
    "assetId": "1234"
  },
  "data": [
    {
      "asks": [
        ["8477", "415", "3"],
        ["8478", "7", "1"]
      ],
      "bids": [
        ["8476", "256", "4"],
        ["8475", "101", "2"]
      ],
      "assetId": "1234",
      "ts": "1710249600000",
      "seqId": 123456
    }
  ]
}

exchangeos-bbo-tbt#

推送买一、卖一各一档的完整 BBO 快照，不是增量更新。BBO 变化时最快每 100 ms 推送一次；100 ms 窗口内的多次变化会合并。盘口无变化时，服务端约每 60 秒保底推送一次。

json
{
  "op": "subscribe",
  "args": [
    {
      "channel": "exchangeos-bbo-tbt",
      "assetId": "1234"
    }
  ]
}
json
{
  "arg": {
    "channel": "exchangeos-bbo-tbt",
    "assetId": "1234"
  },
  "data": [
    {
      "asks": [
        ["8477", "415", "3"]
      ],
      "bids": [
        ["8476", "256", "4"]
      ],
      "assetId": "1234",
      "ts": "1710249600000",
      "seqId": 123457
    }
  ]
}

预估永续结算价格频道 exchangeos-estimated-price#

该频道用于产品下架时推送预估结算价格。订阅成功后会推送当前快照；价格更新采用约 200 ms 的最小聚合窗口，同一 assetId 在窗口内仅推送最新值。无有效预估价格时，settlePx 返回空字符串。

价格无变化时不发送周期性行情心跳；连接保活使用公共 WebSocket 的 ping / pong。expTime、settleAt、status、settlePx、settleType 或其他公开字段变更时，服务端会推送完整对象。当前原始接口示例仅明确定义以下字段。

json
{
  "op": "subscribe",
  "args": [
    {
      "channel": "exchangeos-estimated-price",
      "assetId": "9102"
    }
  ]
}
字段类型说明
assetIdString永续合约资产 ID。
nameString产品名称。
marketTypeString市场类型，例如 perp。
expTimeString预计下架或到期时间，Unix epoch 毫秒。
settlePxString预估结算价格；尚无有效价格时为空字符串。
tsString推送时间，Unix epoch 毫秒。
json
{
  "arg": {
    "channel": "exchangeos-estimated-price",
    "assetId": "9102"
  },
  "data": [
    {
      "assetId": "9102",
      "name": "UNI-USD-PERP",
      "marketType": "perp",
      "expTime": "1751990400000",
      "settlePx": "6.4182",
      "ts": "1751988600123"
    }
  ]
}
目錄