OKX API Key 怎么创建：现货、永续合约与模拟盘配置

先判断你是否真的需要 API Key

公开行情接口通常不需要账户 API Key。只有读取余额、账单、持仓、订单，或执行下单与撤单时，才需要私有接口和签名凭据。先把任务写成一句话，可以避免为了“以后可能用到”而多开权限。

一个 Key 应只对应一个应用、一个环境和一个用途。资产看板通常只读；交易机器人需要读取和交易，但不需要提币。这样某个程序出问题时，可以只撤销对应 Key，不影响其他服务。

使用场景	读取	交易	提币	推荐边界
资产或税务导出	开启	关闭	关闭	只读，不能下单
预警与监控	开启	关闭	关闭	线上部署时尽量绑定 IP
交易机器人	开启	按需开启	关闭	单独 Key、固定 IP、应用内限制订单
自动提币	开启	按需	独立评审后才考虑	与交易程序隔离，不与机器人共用 Key

官方限制里最容易漏掉的三个数字

规则	官方值	对实际部署的影响
权限类型	3	Read、Trade、Withdraw 要逐项选择，不存在“机器人就必须全开”
单 Key 可绑定 IP	最多 20 个	可覆盖多出口部署，但应只填写真实生产出口
非 IP Key 不活跃失效	14 天	带 Trade 或 Withdraw 且未绑定 IP 的 Key 可能在不活跃后失效；需要监控和轮换

14 天规则只针对未绑定 IP、且带 Trade 或 Withdraw 权限的 Key。只读 Key 和已绑定 IP 的 Key 不属于这一失效条件；模拟交易 Key 也不适用。仍建议定期盘点长期不用的 Key 并主动删除。

三种常见用途应该怎样配置

案例	需要的数据或动作	建议权限	额外控制
资产与税务看板	余额、成交、账单	Read	每日拉取，密钥只放服务端
价格与持仓提醒	公共行情、账户持仓	Read	公共行情不用私钥；账户数据才使用 Key
自动下单机器人	查询账户、下单、撤单	Read + Trade	固定 IP、标的白名单、单笔和单日限额、紧急撤销开关

Withdraw 不属于普通交易机器人的必需权限。 如果业务确实需要自动出金，应拆成单独服务、单独 Key、单独审批和独立额度，而不是给主交易程序顺手加权。

OKX 永续合约 API Key 怎么创建？

在交易账户的 API 设置中创建交易所 API Key，先开 Read，确认签名成功后再增加 Trade，Withdraw 保持关闭。账户还要先在网页或 App 中设置支持合约的账户模式。USDT 永续合约使用 BTC-USDT-SWAP 这类 instId；现货则使用 BTC-USDT。二者都可调用 POST /api/v5/trade/order，但交易模式、仓位设置、保证金和风险控制不同。

现货和永续合约是否共用一个 API Key？

可以。同一个实盘交易所 Key 在具备 Trade 权限、账户模式和产品权限支持时，可以发送现货与永续合约请求。但如果现货和合约由不同程序负责，仍建议拆成两个 Key：独立密钥更容易分别绑定 IP、限制用途、审计日志和紧急撤销。模拟盘与实盘不能共用 Key。

Trade 权限够不够，是否需要 Withdraw？

普通交易机器人使用 Read + Trade 即可查询账户、下单和撤单，不需要 Withdraw。多开 Withdraw 不会让订单更容易成交，只会扩大凭据泄露后的风险。如果业务确实要自动提币，应使用独立服务、独立 Key、独立审批和单独额度，不与主交易程序共用。

OKX 模拟盘 API Key 如何创建？

进入交易 → 模拟交易 → 个人中心 → 模拟盘 API，创建专用 Demo Key。模拟盘 REST 请求还要加入 x-simulated-trading: 1。官方文档说明 Demo Key 不受“未绑定 IP 的 Trade/Withdraw Key 14 天不活跃失效”规则影响。模拟下单成功只能证明请求结构可用，不能证明实盘余额、生产出口 IP 和风控已经正确。

OKX DEX/Onchain API 与交易所 API 有什么区别？

API 类型	在哪里创建凭据	主要用途	资产控制方式
交易所 V5 API	OKX 交易账户 API 设置	中心化现货、永续、账户和订单	资产位于交易所账户
DEX / Onchain API	OKX 开发者门户中的项目	链上询价、路由与交易构建	用户钱包签名或发送链上交易

两者的认证概念相似，但项目和 API Key 不是同一套。DEX Key 不会获得中心化交易所的下单权限，交易所 Key 也不是 Onchain 开发者项目的凭据。

最小可运行的 OKX 永续合约请求

下面示例沿用 OKX 官方 Python SDK 的写法，并明确设置为模拟盘。先安装官方 SDK，替换为模拟盘凭据，确认模拟账户模式正确后再运行；不要把实盘 Secret 或 Passphrase 放进代码仓库。

import okx.Trade as Trade

api = Trade.TradeAPI(
    "YOUR_DEMO_API_KEY",
    "YOUR_DEMO_SECRET_KEY",
    "YOUR_DEMO_PASSPHRASE",
    False,
    "1",  # 1 = 模拟盘；0 才是实盘
)

result = api.place_order(
    instId="BTC-USDT-SWAP",
    tdMode="isolated",
    side="buy",
    ordType="limit",
    px="10000",
    sz="1",
)
print(result)

SDK 的 Demo 标记会使用模拟交易行为；如果自己写原始 REST 客户端，则必须完成签名并在请求头加入 x-simulated-trading: 1。示例是模拟环境的请求结构，不是实盘下单建议。

创建 OKX API Key 的完整步骤

1. 先写清楚任务。 这个应用是读取数据，还是会下单、撤单？
2. 通过 OKX 中文注册入口 进入账户，再从账户内打开 API 设置。 为当前应用新建 Key，不复用旧凭据；推荐入口可享受 20% 手续费减免。
3. 按最小权限选择。 默认只读，完成验证后再决定是否增加交易权限。
4. 创建时立即保存三项凭据。 API Key、Secret、Passphrase 放入密钥管理器或加密环境变量，不要发到聊天、代码、截图和日志。
5. 条件允许时绑定稳定出口 IP。 必须确认线上服务器实际对外 IP，而不是开发电脑的 IP。
6. 先调用一个私有读取接口。 例如查询账户余额，确认签名、时间同步、Passphrase 和账户范围都正确。
7. 模拟盘另建凭据。 Demo 请求还要加入 x-simulated-trading: 1；不要把实盘 Key 和 Demo Key 放在同一份配置文件里。
8. 实盘只做极小额验证。 先下单，再查订单状态，最后撤单或平仓；确认应用级限额生效后再正式运行。

第一次接入，按这个顺序最省时间

阶段	只做什么	通过标准	失败时不要做什么
1. 公共接口	获取服务器时间或公开行情	网络、域名和返回格式正常	不要先怀疑 API 权限
2. 私有只读	查询余额或账户配置	签名、时间戳和 Passphrase 均通过	不要直接增加 Withdraw
3. Demo 交易	小额模拟下单并查询订单	下单与订单回查一致	不要把 Demo 成功等同于实盘就绪
4. 实盘小单	极小金额下单、撤单或平仓	权限、账户模式和应用限额均正确	不要第一次就运行完整策略资金

OKX REST 签名如何组成

官方认证说明把时间戳、大写 HTTP 方法、请求路径和请求体拼成待签名字符串，再用 API Secret 做 HMAC SHA-256 并进行 Base64 编码。私有请求还要按文档传递 API Key、签名、时间戳和 Passphrase。

待签名字符串 = 时间戳 + HTTP方法 + 请求路径 + 请求体
签名 = Base64(HMAC_SHA256(Secret, 待签名字符串))

请求路径需要包含查询参数，签名使用的请求体必须与实际发送内容完全一致。GET 没有请求体时按空字符串处理。调试时可以记录脱敏后的待签名字符串，但不能记录 Secret、Passphrase 或完整请求头。

常见认证错误怎样定位

错误或现象	最常见原因	建议排查顺序
50113 Invalid Sign	方法大小写、路径、查询参数、JSON body 或 Base64 结果不一致	打印脱敏后的 prehash；逐字对照实际请求；确认 HMAC 输出再 Base64
50102 Timestamp request expired	服务器时钟不同步或时间戳格式错误	先查 OKX 服务器时间；同步 NTP；确认 UTC 与毫秒格式
50110 IP 不在白名单	实际生产出口 IP 与填写值不同	从运行请求的服务器确认 egress IP，再更新白名单
50101 环境不匹配	Demo Key 与实盘环境混用，或模拟请求头错误	核对 Key 创建位置；Demo 使用 x-simulated-trading: 1
Passphrase 错误	创建时保存的 Passphrase 不一致	不要反复猜测；删除并重建 Key
能查余额但不能下单	Key 没有 Trade，或账户/交易模式不匹配	先查权限，再核对现货、合约及账户模式；不要顺手开 Withdraw

这些问题在真实开发接入里反复出现

• Python POST 下单出现 50113 Invalid Sign，最终定位到请求体与签名字符串不一致：Stack Overflow 案例。
• PHP 调用出现 Invalid Sign，问题出在 HMAC 输出格式与 Base64 处理：Stack Overflow 案例。
• python-okx 查询余额出现 50102，排查集中在服务器时间和 ISO 时间格式：GitHub Issue。
• Freqtrade 使用 OKX 合约时，账户模式与工具支持范围不一致会阻止启动；这不是把权限全开就能解决的问题：GitHub Issue。

这些案例的共同点不是“API 不稳定”，而是签名输入、时间、环境和账户模式必须完全一致。因此最有效的接入方式，是把错误缩小到单一阶段，而不是一开始同时调试签名、交易策略和实盘资金。

上线前检查清单

• 每个集成、每个环境单独 Key；
• Secret 不进入 Git，不打包进浏览器 JavaScript；
• 普通看板和交易机器人关闭提币权限；
• 有稳定出口 IP 时使用白名单；
• 日志脱敏 API Key、Secret、Passphrase 与签名；
• 写清楚撤销、轮换以及服务器 IP 变化后的处理流程；
• 在应用层限制标的、订单金额与最大风险；
• 模拟盘和只读验证通过后，才做小额实盘测试。

完成只读、Demo 和小额实盘验证后，API 才算真正可用。随后可把账户实际显示的 Maker/Taker 费率填入 OKX 手续费计算器，复算交易成本，而不是把公开示例费率当成自己的账单费率。