okv5 API 常见问题全解：请求、签名、错误码一步到位

关键词：okv5 API、APIKey签名、历史数据、错误码、REST请求、JSON格式、HMAC SHA256

一、必带请求头：私钥签名的四大保镖 {#head}

所有 私密接口 必须在请求头加入以下四项，否则寸步难行：

请求头字段	含义与示例	备注
`OK-ACCESS-KEY`	用户公钥（APIKey）	字符串
`OK-ACCESS-SIGN`	经过 HMAC-SHA256+Base64 的签名	见下节「签名」
`OK-ACCESS-TIMESTAMP`	UTC 时间，如 `2020-12-08T09:08:57.715Z`	与签名保持一致
`OK-ACCESS-PASSPHRASE`	创建密钥时自定义的 Passphrase	不能为空

📌 Content-Type 同时必须为 application/json，并附带 有效 JSON 字符串 作为请求体（GET 可省略 body）。

二、签名计算：一条公式告别 401 {#signature}

核心逻辑两步：

拼接待签名串
```
timestamp + method + requestPath + body
```
- 方法一律大写（GET／POST）。
- GET 的参数放入 requestPath，DISABLE body；POST 的参数放 body，requestPath 不含 query。

加密并编码

import hmac, hashlib, base64, json, time, requests

secret = b'YOUR_SECRET_KEY'
ts = '2024-05-20T06:30:00.000Z'
method = 'POST'
path = '/api/v5/account/balance'          # 不含 query
body = json.dumps({
    "instId":"BTC-USDT",
    "lever":"5"
})                                       # 不压缩空格
sign_str = f'{ts.upper()}{method}{path}{body}'.encode()
sign = base64.b64encode(
    hmac.new(secret, sign_str, hashlib.sha256).digest()
).decode()

最终 sign 放到请求头 OK-ACCESS-SIGN 即可。

三、典型故障速判表 {#trouble-shoot}

3.1 Bad Request（-1）

原因：时间戳格式不符合 Unix 毫秒。
解决：

after = str(int(time.mktime(
    datetime(2021, 8, 3, 1, 14, 22).timetuple()
)) * 1000)

3.2 OK_ACCESS_KEY 错误 50103

排查三板斧：

公钥是否复制完整；
当前环境（模拟盘 / 正式盘）是否对应；
私密接口未打标签 private:0 却被当作私密调用。

3.3 提币报「Please add a withdrawal address」58203

内部转账「A → B」需：

B 的 UID 存在于 A 的地址簿；
预设为「免验证」，否则赶回地址簿加签。

3.4 已平仓却仍显示持仓

真·逐仓仓位需等待 24 h 以上、系统结算后才自动清零；全仓仓位排在后，切勿重复点击刷新。

四、错误码黑频闪避指南 {#error-code}

下面 30+ 代码按 HTTP 状态码 + 描述 帮你快速锁定源头。

通用类

50000 body 不能为空
50002 JSON 不合法
50004 请求超时（需轮询订单状态再确认）
50011 IP 被风控限速（429，降低并发）
50027 账户受限交易（需人工解封）

API 类

50102 时间戳过期（与服务器误差 >30 秒）
50111 无效 OK_ACCESS_KEY（密钥未启用或环境不匹配）
50113 签名非法（拼接顺序、大小写、多余空格等）

FAQ：3 分钟解决最头痛疑问 {#faq}

Q1：Python 发起 POST 应当传 dict 还是 JSON？
A：必须 json.dumps(dict) 得到字符串；否则后端反序列化失败返回 50000。

Q2：模拟盘与正式盘APIKey能否混用？
A：不行。必须在对应环境下新建，否则会收到「APIKey与当前环境不匹配 50101」。

Q3：出现「无效的ip 50110」怎么办？
A：在个人中心—API 管理，把当前出口 IP 添加进白名单，支持 CIDR。

Q4：历史K线一次最多拉多少条？
A：单条请求上限 100 根（max_len=100），需循环分页继续抓。👉 点击这里获取完整批量抓取示例代码，10 秒钟复制可用！

Q5：如何检测“强平冻结中”？
A：监听 50020~50022 错误，冻结中禁止任何平仓、追加保证金或杠杆调整操作。

Q6：查询逐仓仓位时，需要传哪些参数？
A：携带 instType=SWAP 和当前逐仓仓位 instId，不传时默认返回全仓。

五、实测流程：从连接 ping 到下单回执 {#demo}

启动时钟，同步系统时间（NTP 校准 UTC ±500 ms）。
检测 GET /api/v5/users/self/verify 成功返回用户昵称后，确认签名逻辑无瑕疵。

模拟下单：

curl -X POST https://www.okx.com/join/8265080api/v5/trade/order \
     -H "OK-ACCESS-KEY: YOUR_KEY" \
     -H "OK-ACCESS-SIGN: GENERATED_SIGN" \
     -H "OK-ACCESS-TIMESTAMP: 2024-05-20T06:30:00.000Z" \
     -H "OK-ACCESS-PASSPHRASE: YOUR_PASS" \
     -H "Content-Type: application/json" \
     -d '{"instId":"BTC-USDT","tdMode":"isolated","side":"buy","ordType":"limit","px":"27000","sz":"0.02"}'

六、写在最后 {#end}

当你有能力 1 分钟定位签名错误、3 句代码修正格式 时，高频量化 的第一道门槛就打穿了。
👉 现在就去双手体验极速低延迟交易环境！