概览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最新成交价。
lastSzString最新成交数量。
askPxString卖一价。
askSzString卖一量。
bidPxString买一价。
bidSzString买一量。
open24hString24 小时开盘价。
high24hString24 小时最高价。
low24hString24 小时最低价。
volCcy24hString24 小时成交额（计价货币）。
vol24hString24 小时成交量（基础货币）。
sodUtc0StringUTC+0 时区的日开盘价。
sodUtc8StringUTC+8 时区的日开盘价。
tsString数据更新时间戳，使用 Unix 毫秒。
lastPxUsdString最新成交价的美元价值。
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#

频道说明

推送指定产品的最近成交数据。

成交聚合逻辑

exchangeos-trades 按 assetId 独立处理成交数据。

连续收到的成交记录同时满足以下条件时，会被合并为一条聚合记录：

  • 成交价格相同。
  • 买卖方向相同。
  • 时间戳相同，精确到毫秒。
  • 价格精度和数量精度相同。

合并后，成交数量会累加。只要任一条件不同，系统就会生成一条新的记录。

推送规则

  • 系统通常每 100 毫秒检查一次成交数据。
  • 每次最多返回最新的 20 条聚合记录。
  • data 数组中的记录按时间倒序排列，最新成交在前，较早成交在后。
  • data 中的每条记录可能代表一笔原始成交，也可能代表多笔满足上述条件的相邻成交的聚合结果。
  • assetId 仅出现在 data 数组的第一个元素中。同一消息帧中的成交均属于同一个 assetId，外层 arg.assetId 已标识对应产品。
json
{
  "op": "subscribe",
  "args": [
    {
      "channel": "exchangeos-trades",
      "assetId": "1234"
    }
  ]
}
字段类型说明
assetIdString产品 ID，仅出现在 data 数组的第一个元素中。
fIdString聚合段内第一笔原始成交的成交 ID，包含边界。
lIdString聚合段内最后一笔原始成交的成交 ID，包含边界；首字符为小写字母 l。聚合段内的成交 ID 保证从 fId 到 lId 连续。
pxString聚合段内所有成交的共同成交价格。
szString聚合段内的成交数量总和。
sideString成交方向，可取 buy 或 sell。
tsString成交时间，使用 Unix 毫秒时间戳。同一条聚合记录内所有成交的 ts 相同；ts 不同的成交不会被聚合。
json
{
  "arg": {
    "channel": "exchangeos-trades",
    "assetId": "1802"
  },
  "data": [
    {
      "assetId": "1802",
      "fId": "161999",
      "lId": "161999",
      "px": "94.546",
      "sz": "1.05",
      "side": "buy",
      "ts": "1793087643641"
    },
    {
      "fId": "161998",
      "lId": "161998",
      "px": "94.54",
      "sz": "1.17",
      "side": "buy",
      "ts": "1793087643641"
    }
  ]
}

成交 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#

频道说明

推送产品上下线及交易品种、交易参数的变更。

增量触发场景包括：

  1. 产品状态 state 发生变化，例如新合约或交易对上线、人工暂停或恢复、交割或行权下架。
  2. 交易参数 priceDecimals 或 sizeDecimals 发生变化。
  3. 产品上线或下线时间 listTime 或 expTime 发生变化。

upcChg 用于推送即将生效的 priceDecimals 或 sizeDecimals 变更。当参数被调整时，系统会推送变更参数名称、新值和生效时间：

  1. 参数变更任务生成时推送一次。
  2. 参数达到生效时间并正式更新后，再推送一次。

产品下架公告会在正式下架前 30 分钟推送。

订阅参数

参数类型必填说明
channelString是固定为 exchangeos-instruments。
instTypeString是产品类型，可取 SPOT 或 PERPS。按产品类型批量订阅。

订阅后，系统会返回指定产品类型下的全部产品，并持续推送该类型产品的上下线及参数变更。任一产品发生变化时，系统会推送该 instType 下的完整产品列表。

订阅示例

json
{
  "op": "subscribe",
  "args": [
    {
      "channel": "exchangeos-instruments",
      "instType": "SPOT"
    }
  ]
}

推送字段（data 元素）

字段名类型说明
instTypeString产品类型，可取 SPOT 或 PERPS。
assetIdString产品 ID，例如 1234。
baseTokenIdString交易货币 ID，仅适用于现货产品。
quoteTokenIdString计价货币 ID，仅适用于现货产品。
settleTokenIdString盈亏结算及保证金货币 ID，仅适用于永续合约。
priceDecimalsString价格精度，即下单价格的最小变动单位。精度调小时，可能触发存量订单价格取整：卖单向上取整，买单向下取整；取整后价格为 0 时，订单将被取消。
sizeDecimalsString数量精度。
stateString产品状态：live 表示交易中，preopen 表示预上线。产品在后台上线且数据完成上链后，系统会推送 preopen 状态。
listTimeString产品上线时间，Unix epoch 毫秒时间戳。
expTimeString产品下线时间，Unix epoch 毫秒时间戳；发生变更时推送。
upcChgArray即将生效的参数变更列表；无变更时返回空数组 []。
upcChg[].paramString即将变更的参数名称，可取 priceDecimals 或 sizeDecimals。
upcChg[].newValueString即将生效的新参数值。
upcChg[].effTimeString参数生效时间，Unix epoch 毫秒时间戳。
tsString事件推送时间，Unix epoch 毫秒时间戳。

参数变更生命周期示例

以下示例表示 priceDecimals 将从 1 变更为 2，生效时间为 1710086400000。

1. 待生效推送

顶层字段仍保留旧值，upcChg 携带新值和生效时间。

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

2. 生效确认推送

达到 effTime 后，顶层字段更新为新值，upcChg 清空。

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

持仓总量频道 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"
    }
  ]
}
目錄