OKX 的 API 和其他交易所有几个不一样的地方：密钥除了 API Key、Secret Key，还多一组自己设置、忘了就找不回来的 Passphrase；没绑 IP 又有交易权限的密钥，闲置 14 天会被系统删掉；下单限速是“每个交易对各自计算”，而不是整个账户共用一个额度。这篇依 OKX 官方 API 文档（v5）与说明中心整理，数字截至 2026-09-28，以官方页面为准。返佣对量化策略损益的影响，已经写在量化交易手续费返佣，这里只讲怎么把程序接上 OKX。用 NOVA888 注册 OKX，享 20% 自动返佣；另有我们独家的 OKX 奖励和优惠活动，请洽客服。
先搞懂三组凭证：API Key、Secret Key、Passphrase
创建密钥后，系统会给你随机产生的 API Key 与 Secret Key；Passphrase 则是你在创建时自己输入的密码。官方文档写明，OKX 只保存 Passphrase 的加盐哈希值，忘记就无法找回，只能删掉旧密钥重新建一组。三组都要存在安全的地方，创建后也看不到 Passphrase 了。
每个私有请求都要带四个标头：OK-ACCESS-KEY、OK-ACCESS-SIGN（签名）、OK-ACCESS-TIMESTAMP、OK-ACCESS-PASSPHRASE。时间戳要用 UTC 的 ISO 8601 格式、精确到毫秒，和服务器时间差超过 30 秒就会被拒（错误码 50102）。官方 FAQ 提醒最常见的原因是用了本地时区，建议下单前先用 GET /api/v5/public/time 对时。
创建密钥：网页、App 与子账户
官方〈API 常见问答〉列的路径：
- 网页：登录 → 个人数据 →“API 与连接”→ 创建 API Key → 填名称 → 选择账户与用途 → 填 IP 白名单 → 选权限 → 设置 Passphrase。
- App：登录 → 菜单（⋮⋮⋮）→ 往下找到 API → 创建 API Key，后面步骤相同。
几个容易卡关的地方：
- 资产门槛：官方写明，部分地区的主账户或子账户，资产（AUM）要超过 100 USD 才能创建 API Key。
- 子账户要用自己的密钥：在要交易的子账户底下创建密钥，使用该子账户的权限与 Passphrase；主账户和子账户的 Key、Secret、Passphrase 不要混用。
- API 网域依注册站点而定：官方文档写明，在 app.okx.com 注册的美国与澳洲用户要用 us.okx.com，在 my.okx.com 注册的欧洲用户要用 eea.okx.com；网域不对会出现“50119 API key doesn't exist”。
- 账户模式要先在网页或 App 设置：现货、合约、跨币种保证金、组合保证金四种模式，第一次都要在接口上设置；在现货模式下用 API 下合约单会回 51010。
权限怎么选：读取、交易、提币
| 权限 | 官方定义 | 量化策略需要吗 |
|---|---|---|
| 读取（Read） | 查询账单、订单历史等需要读取权限的信息 | 需要 |
| 交易（Trade） | 下单、撤单、资金划转、需要写入权限的设置 | 需要 |
| 提币（Withdraw） | 发起提币 | 不需要，不要开 |
交易权限底下另外有三个细项：划转（账户之间转资金，所有账户都有）、借贷与赚币（账户符合资格才看得到）。官方说明，原本已开交易权限的密钥，这三项会自动一起打开；创建或编辑密钥时，顺手确认策略是否真的需要借贷与赚币。
另外，就算开了提币权限，要用 API 提币，提币地址还必须先在网页加入地址簿并勾选免验证，否则会回 58207。这是 OKX 刻意加的一道关卡，量化程序根本不需要走到这一步，提币一律回到网页或 App 手动处理。
14 天规则：没绑 IP 的密钥会自动失效
这是 OKX 和其他交易所最不一样的一条。官方 API 文档写明：
- 每把密钥最多绑 20 个 IP，支持 IPv4、IPv6 与网段格式。
- 没绑 IP、且有交易或提币权限的密钥，闲置 14 天后会失效（官方 FAQ 的写法是自动删除）。模拟交易的密钥不会失效。
- “使用”的定义很严格：只有调用需要密钥验证的私有接口才算；调用公开接口时就算带了密钥信息，也不算使用。
- WebSocket 只有“登录”那一下算使用密钥；登录后在同一条连接上订阅、下单都不算。
- 没绑 IP 但有交易／提币权限的密钥，使用纪录可以在安全中心查到。
最后两点对量化策略影响最大：如果你的机器人一直挂在同一条 WebSocket 连接上下单、很少重新登录，又没有绑 IP，就可能在策略还在跑的时候碰到密钥失效。
最省事的做法就是把策略服务器的固定 IP 绑上去。绑了 IP 的密钥不受 14 天闲置规则影响，外流时也只能从你的服务器使用，一次解决稳定性和安全性两个问题。
模拟交易：先用虚拟资金跑一遍
OKX 的模拟交易可以直接用 API 串接，官方文档写的流程是：登录 OKX →〔交易〕→〔模拟交易〕→ 个人中心 → 模拟交易 API → 创建模拟交易 API Key。和正式环境的差别：
| 项目 | 正式环境 | 模拟交易 |
|---|---|---|
| 密钥 | 正式账户创建的密钥 | 必须用模拟环境另外创建的密钥 |
| REST 请求 | — | 标头加上 x-simulated-trading: 1 |
| WebSocket | wss://ws.okx.com:8443 | wss://wspap.okx.com:8443（public／private／business 三个路径） |
| 不支持的功能 | — | 提币、充值、申购／赎回等 |
| 密钥失效 | 适用 14 天规则 | 不会失效 |
密钥和环境对不上会回“50101 APIKey does not match the current environment”：正式密钥要配 x-simulated-trading: 0（或不带），模拟密钥要配 1。官方另外提供网页版的 Demo Trading Explorer，登录后可以直接在浏览器试打模拟环境的接口，适合先确认参数格式。
限速：每个交易对各自计算
OKX 的限速逻辑和“整个账户一个额度”不同。官方文档写明：公开接口依 IP 限速；私有 REST 接口依 User ID 限速（每个子账户各自有 User ID）；下单、改单、撤单的额度彼此独立；REST 与 WebSocket 共用同一份额度；而下单类的限速是以“交易对（Instrument ID）”为单位。超过时回错误码 50011。常用端点（截至 2026-09-28）：
| 端点 | 限速 | 计算单位 |
|---|---|---|
下单 POST /api/v5/trade/order | 每 2 秒 60 次 | User ID + 交易对 |
| 批量下单（每次最多 20 笔） | 每 2 秒 300 笔订单 | User ID + 交易对 |
| 撤单 | 每 2 秒 60 次 | User ID + 交易对 |
查余额 GET /api/v5/account/balance | 每 2 秒 10 次 | User ID |
查手续费率 GET /api/v5/account/trade-fee | 每 2 秒 5 次 | User ID |
| 带单员的带单交易对 | 每 2 秒 4 次 | — |
在交易对的限速之外，还有一层子账户总量限制：每 2 秒最多 1,000 个新单与改单请求（批量单逐笔计算），超过回 50061。两层限制同时运作。官方文档的最佳实务直接建议：需要更多额度时，把策略拆到不同子账户，让每个账户各自用满额度。
手续费等级 VIP5 以上的账户，另外适用“成交率”分级：系统每天依过去 7 天的成交量与下单／改单次数计算比率，最高一级每 2 秒可达 10,000 个请求；比率下降时有一天缓冲期。现货与杠杆订单不受子账户总量限制。可以用 GET /api/v5/trade/account-rate-limit 查自己目前的额度。
WebSocket：连接、订阅与心跳
- 创建连接：每个 IP 每秒最多 3 次连接请求。公开频道连 public 地址，私有频道连 private 地址。
- 订阅次数：每条连接每小时的 subscribe／unsubscribe／login 请求合计最多 480 次。
- 心跳：订阅没创建、或超过 30 秒没有数据推送，连接会自动断开。官方建议每收到一则消息就重设一个小于 30 秒的计时器，逾时就送字符串
ping，收不到pong就重连。 - 私有频道连接数：订单、账户、持仓等频道，每个子账户每个频道最多 30 条连接，超过时通常是最新的那条被拒。通过 WebSocket 下单、改单、撤单不受这条影响。
官方 FAQ 还提到一个实务细节：每天 8 点、16 点、24 点是收取资金费的时间点，服务器压力较大（官方原文未注明时区），这时可能出现“50004 API endpoint request timeout”；50004 不代表下单失败或成功，要再查询实际结果，不要直接重送同一张单。
如果担心程序当机或断线后单子还挂在簿上，可以用 POST /api/v5/trade/cancel-all-after 设倒数计时：时间到还没重设，就自动撤掉所有挂单（限速每秒 1 次）。
代码范例：签名并查询手续费率
OKX 的签名方式是把“时间戳 + 请求方法（大写）+ 请求路径 + 请求内容”串成一个字符串，用 Secret Key 做 HMAC SHA256，再做 Base64 编码。GET 请求的参数算在路径里。下面示范在模拟环境查询 BTC-USDT 现货的手续费率，只需要读取权限；三组凭证都从环境变量读取。
import base64, hashlib, hmac, os
from datetime import datetime, timezone
import requests
key = os.environ["OKX_API_KEY"]
secret = os.environ["OKX_SECRET_KEY"]
passphrase = os.environ["OKX_PASSPHRASE"]
path = "/api/v5/account/trade-fee?instType=SPOT&instId=BTC-USDT"
ts = datetime.now(timezone.utc).isoformat(timespec="milliseconds").replace("+00:00", "Z")
prehash = ts + "GET" + path
sign = base64.b64encode(hmac.new(secret.encode(), prehash.encode(), hashlib.sha256).digest()).decode()
headers = {
"OK-ACCESS-KEY": key,
"OK-ACCESS-SIGN": sign,
"OK-ACCESS-TIMESTAMP": ts,
"OK-ACCESS-PASSPHRASE": passphrase,
"x-simulated-trading": "1",
}
r = requests.get("https://openapi.okx.com" + path, headers=headers, timeout=10)
print(r.status_code, r.json())换到正式环境时，改用正式账户的密钥、拿掉 x-simulated-trading 标头；美国、澳洲与欧洲用户记得换成各自的 API 网域。
API 下单的手续费与 maker 单
与其套公开费率表，不如直接用上面范例的 GET /api/v5/account/trade-fee 查自己账户目前的实际费率。官方文档写明，现货／杠杆查询时带上 instId，回传的才是正确适用的费率（例如参加激励计划用户的做市商费率）。各等级的公开费率见 OKX VIP 手续费等级。
要确保只当 maker，下单时把 ordType 设成 post_only。官方定义是：这种单只能提供流动性、成为 maker，如果下单当下会直接成交，就会被取消。maker／taker 的差别与省下的金额，见 Maker／Taker 手续费说明。
API 交易和返佣：OKX 条款怎么写
我们读了 OKX 联盟计划规则（2026-09-07 更新）与经纪商规则（2026-08-05 更新）。联盟规则的写法是：邀请人就受邀用户支付的每一笔交易手续费取得分成，涵盖现货、合约、期权。规则里没有针对“自己用 API 下单”另外写计入或不计入，因此这部分以 Quant Nova 每日结算明细为准。官方有明写、和程序交易者直接相关的是：
- 通过经纪商下单：经纪商规则写明，经由联盟邀请注册、再通过经纪商（API 经纪商或 OAuth 经纪商）交易的用户，分成会分别给联盟与经纪商。
- 不产生分成的情况：交易的币种不收手续费；用返佣卡、合约体验金、抵用券抵扣手续费；享有特殊费率；交易者本身是做市商或经纪商；使用托管子账户；手续费等级 VIP7 以上。
换句话说，参加 OKX 做市商计划、或用托管子账户跑策略的账户，官方写明不在分成范围内，开始之前要先确认。
通过 Quant Nova 用 NOVA888 注册 OKX，享 20% 自动返佣；另有我们独家的 OKX 奖励和优惠活动，请洽客服。绑定只需要 UID，不需要把 API 密钥交给任何人。邀请码与注册链接见 OKX 邀请码 NOVA888，返佣怎么计算见 OKX 手续费返佣攻略；已经有账号的话，先看 OKX 换绑教学。在其他交易所已经是 VIP、或交易量大的量化团队，欢迎联系 Quant Nova 客服，我们会直接对接交易所官方窗口，帮你争取 VIP 等级试用等福利（实际以交易所核定为准）。
安全与防诈：密钥不交给任何人
OKX 的 API 协议（2026-07-28 更新）把责任写得很清楚：密钥的产生、保管、轮换与撤销都由用户自己负责，不得把密钥分享给未经授权的人，怀疑外流就要立刻撤销。协议也把“把 API 访问权或凭证交给未经授权的第三方”列为禁止行为，并写明未经 OKX 事先书面同意，不得用 API 替第三方操作账户或下单。
要接第三方机器人或交易平台时：
- 优先用 OAuth 授权：OKX 经纪商规则说明，OAuth 经纪商是通过 OKX App 或网页授权，用户不需要把自己的 API 密钥交出去。
- 一定要贴密钥时，只给读取＋交易，绑上对方公布的服务器 IP，并确认借贷、赚币等细项是否真的需要。
- 向客服回报问题时，官方 FAQ 提醒：绝对不要提供 Secret、Passphrase、验证码或未屏蔽的签名。
“代操”是最常见的骗局：对方自称量化团队或操盘手，要你建一把密钥给他、保证固定月报酬。有提币权限的密钥，不论对方是谁、怎么保证，都不要交出去；就算只有交易权限，对方也能用高杠杆把保证金赔光。
金管会 2025-09-22 公告完成洗钱防制登记的 VASP 名单时再次提醒：诈骗集团多以“稳赚不赔”、“高获利低风险”等话术，诱导民众购买虚拟资产，嗣后再借口需支付解冻金、保证金或税款等，要求民众缴纳额外款项后方得领回投资报酬。（金管会新闻稿）
台湾用户另外要知道：截至 2026-09-28，OKX 不在金管会“已完成洗钱防制登记之提供虚拟资产服务之事业或人员”名单上，名单怎么查与各家状态见金管会 VASP 登记名单。
常见问题
OKX 的 Passphrase 忘记了怎么办？
无法找回。OKX 只保存 Passphrase 的哈希值，只能删掉这把密钥、重新创建一组。
OKX API 密钥为什么突然失效？
最常见的原因是没绑 IP、又有交易或提币权限，闲置 14 天后被系统删除。WebSocket 只有登录算使用，连接上的下单不算；绑上固定 IP 就不受这条规则影响。
一把密钥可以绑几个 IP？
最多 20 个，支持 IPv4、IPv6 与网段格式。
OKX 下单限速是多少？
单笔下单每 2 秒 60 次、批量下单每 2 秒 300 笔，都是以 User ID + 交易对计算；另外每个子账户每 2 秒最多 1,000 个新单与改单请求。REST 与 WebSocket 共用额度。
模拟交易的 API 怎么用？
在模拟交易的个人中心另外创建密钥，REST 请求标头加 x-simulated-trading: 1，WebSocket 改连 wspap.okx.com。模拟密钥不会因闲置失效。
用 API 交易能拿返佣吗？
OKX 联盟规则是就受邀用户支付的每笔交易手续费分成，没有针对自己用 API 下单另外写，以结算明细为准；经纪商规则则写明，联盟邀请的用户通过经纪商交易，分成会分别给联盟与经纪商。做市商、托管子账户与 VIP7 以上不产生分成。
Telegram · @quant_nova
LINE · @238pqnkj