功能定位：为什么子账户必须再拆权限

在 OKX（原 OKEx）主-子账户模型里，子账户天生拥有独立仓位、独立费率阶梯、独立 API 速率三大优势；然而一旦把“交易+提币+划转”一次性全开，就等于把金库钥匙交给策略脚本。2026 年 Q1 起，平台将权限颗粒度从“功能模块”细化到“币对+指令+IP”三维，核心关键词“OKX 子账户 API Key 权限细分”正是堵住“策略越权”与“单点泄露”的最后一块拼图。

经验性观察：同一量化团队把“只读”与“交易”分离后，异常下单事件下降一个数量级。可复现验证：在沙箱子账户只给读取权限，脚本尝试下单会返回 403，日志可见 reject reason=Permission denied。

前置检查：五步调平账户结构

主账户完成Pro 级 KYC（子账户才能开 API）。
子账户已激活且资产隔离（设置→子账户→划转→“隔离模式”开关打开）。
子账户已绑定谷歌或 Yubikey，禁止短信单因子。
主账户未开启“全局 API 提币”总闸（安全→API→高级设置→“允许子 API 提币”默认关）。
已准备可信静态 IP（云服务器弹性 IP/办公室固定 IP），动态 IP 将在第四节解释风险。

若第 4 项总闸被误开，系统会在创建子 API 时弹红字提醒，但仍允许继续；最佳实践是先锁总闸再往下走，防止后期遗忘。

操作路径：最短入口与平台差异

桌面 Web 端（以当前最新版本为例）

右上角头像→API 管理→子账户列表→选中目标子账户→“创建 API”→进入“细分权限”页。

iOS/Android App v6.97.0

资产页→右上角“⋮”→API 管理→子账户→选择子账户→“+”→同样进入“细分权限”页；差异点：App 默认折叠“币对权限”模块，需要手动展开。

提示：若你在 API 列表页看不到子账户，回到“子账户管理”先点“激活 API 功能”，系统会分配独立 Rate-Limit，无需等待。

三维权限模型：币对×指令×网络

维度	可选项	最小化建议
币对范围	ALL / 自选列表 / 单币对	网格策略只开 BTC-USDT、ETH-USDT 两对，防止脚本误操作低流动性小币。
指令类型	读取/下单/撤单/划转/充提	做市程序只给“读取+下单+撤单”，拒绝“划转”可阻断黑客提币路径。
网络/IP	0.0.0.0/0 或 CIDR 白名单	绑定 /32 固定 IP，并启用“拒绝非白名单”开关，系统会强制拒绝异地请求。

设置完成后，系统会生成Passphrase（仅显示一次），请立即写入 .env 并删除剪贴板记录；丢失后只能删除重建。

场景映射：四组最小权限模板

1) 只读风控面板

需求：公司风控后台每 30 秒拉取持仓与权益，禁止任何下单。
模板：币对=ALL，指令=读取，IP=内网两台服务器/32。实测延迟 180 ms 内，无额外限频。

2) 高频做市策略

需求：在 BTC-USDT、ETH-USDT 两对持续挂单，不触发提币。
模板：币对=自选列表（仅两对），指令=读取+下单+撤单，IP=托管机房/32，Rate-Limit=120 req/s。

3) 跨所搬砖自动结算

需求：当价差>阈值时，需把 USDT 从资金账户划转到交易账户。
模板：币对=ALL，指令=读取+划转，IP=云主机/32；注意“划转”权限不包含提币，仍无法转出平台。

4) 期权波动率卖权

需求：仅交易 BTC-USD-期权，且需提交 Calendar Spread 组合。
模板：币对=BTC-USD-OPTIONS，指令=读取+下单+撤单，IP=办公室/32；若误选现货币对，系统会返回 bad instrument。

例外与取舍：什么时候不能细分

统一保证金模式下，子账户仍共享主账户的 U 本位风险限额；若策略需要独立限额，必须再开“独立保证金”子账户，否则细分权限无法隔离风险。
跟单社区（Copy Trading）API 目前仅支持“主账户”接入，子账户 API 无法发布信号；此限制在官方文档已列明，无需尝试。
NFT 市场的扫货接口暂不在 API 开放列表，即使给“ALL”权限，调用 /api/v5/market/nft/orders 也会返回 404。

警告：若把 IP 设为 0.0.0.0/0 但又勾选“拒绝非白名单”，系统会优先拒绝所有请求，导致看似“API Key 失效”；此时需在控制台删除旧白名单或关闭“拒绝”开关。

例外与取舍：什么时候不能细分

与第三方机器人协同：最小化密钥原则

经验性观察：多数“网格机器人”只需要读取+下单+撤单三权限，却默认申请“划转+提币”。可复现验证：在测试子账户仅勾选前三项，机器人仍能完成双向挂单与止盈，日志无 missing scope 报错；若机器人强制要求提币权限，应视为高风险。

对接流程建议：

在 OKX 子账户创建“最小权限”Key，Passphrase 写入本地加密文件。
在第三方面板只填 API Key+Secret+Passphrase，不勾选“允许提币”；若面板无权限开关，优先更换服务商。
启用“日志告警”→过滤 reject reason，出现 insufficient privilege 立即停单复核。

故障排查：现象→原因→验证→处置

现象	可能原因	验证步骤	处置
返回 403，msg=IP forbidden	IP 不在白名单	curl -H "OK-ACCESS-KEY:xxx" https://www.okx.com/api/v5/account/balance 从服务器 A/B 分别请求	在 API 管理→编辑→IP 白名单添加当前出口 IP/32
返回 400，msg=Invalid instrument	币对权限未包含该标的	调用 /api/v5/public/instruments?instType=SWAP 确认是否在列表	回到权限页把该币对加入自选列表
返回 409，msg=Risk limit exceeded	子账户风险档位不足	在交易设置→风险限额查看当前档位	手动提高一档或降低杠杆

适用/不适用场景清单

≥3 人的量化团队：必须启用子账户+细分权限，避免实习生脚本误操作全仓。
单账户散户：若仅用手机 APP 手动交易，不开 API 反而减少攻击面。
需要随时异地登录：动态 IP 用户若无法固定白名单，应放弃“IP 拒绝”开关，改用 24h 提币冷却+Yubikey，防止因 IP 漂移把自己锁死。
高频做市：需要 /32 固定 IP+120 req/s 速率，若机房出口为 NAT 多 IP，需让服务商提供独享公网 IP，否则会出现随机 403。

最佳实践速查表

1. 总闸：主账户关闭“子API提币”
2. 权限：最小集合=读取+必要指令，拒绝ALL
3. 币对：策略用到几对就开几对
4. IP：/32固定，启用“拒绝非白名单”
5. 密钥：Passphrase写入硬件加密盘，CI/CD用变量注入
6. 监控：日志过滤reject，>5次/小时自动停策略
7. 轮换：90天强制删除重建，避免旧Key泄露
8. 灾备：主账户保留一把“只读”Key，防止子账户被误删后无法查看仓位

FAQ（结构化数据，便于搜索引擎抓答案）

子账户 API Key 能否提币？

默认不能。主账户需在“安全→API→高级设置”手动打开“允许子 API 提币”总闸，且子 Key 显式勾选“提币”权限，两项同时满足才能提币。

一个子账户可以建几个 API Key？

最多 5 组，每组独立 Rate-Limit；若团队策略>5，需再建新的子账户。

IP 白名单支持 IPv6 吗？

截至当前最新版本，仅支持 IPv4 CIDR；IPv6 会在保存时提示格式错误。

删除子 Key 后，正在跑的策略会怎样？

系统立即失效签名，策略会收到 403，仓位不会自动平仓，需用主账户或其他子 Key 接管。

可以批量导入币对吗？

Web 端支持 CSV 上传（最大 500 行），模板可在“细分权限”页下载；App 端只能手动勾选。

收尾：下一步行动

OKX 子账户 API Key 权限细分并非“多此一举”，而是把“策略”“风控”“合规”拆成三道门。读完本文，你只需：

打开子账户→按速查表建“最小权限”Key；
把 Passphrase 写进加密盘，CI/CD 用变量注入；
打开日志监控，今晚就能让脚本在“只读+下单”沙箱里跑起来，而黑客即使拿到 Key，也只剩 403 陪伴。

量化路上，少即是多——权限越小，睡得越香。

OKX子账户API Key权限如何细分设置？