python-okx 从装环境到跑通交易一份不再踩坑的完整排障手册【免费下载链接】python-okx项目地址: https://gitcode.com/GitHub_Trending/py/python-okx你是不是也用 python-okx 下单时报过 401或者 WebSocket 刚订阅就掉线本手册按开发场景把排障拆成 4 组接入与鉴权、REST 数据读写、实时通道、生产兜底对号入座直接跳。你看到的现象跳到哪一句话根因安装报依赖冲突1.1Python 版本低于 3.9下单报 401 或连不上1.2flag 没切对实盘测试网串了接口返回 401 / 4031.3密钥权限或 IP 白名单问题签名验证失败 100001.4系统时间与服务器偏差过大place_order 报精度错误2.1价格小数位超过合约 tick历史订单拉不全2.2分页 after 没循环翻页WebSocket code1006 断连3.1没发心跳或订阅过多私有频道登录失败3.2测试网 WS 地址写错进程因异常直接退出4.1没按三类异常分别捕获请求返回 4294.2频率超限没加 sleepK 线接口被反复请求4.3没做本地缓存接入与鉴权版本检查、测试网切换、错误码排查Python 低于 3.9安装冲突怎么查现象群里喊pip install python-okx 怎么装都报依赖冲突。根因库要求 Python ≥ 3.9低于这个版本会与 httpx 等依赖产生版本冲突。下面这条命令先确认版本达标后再装最新版python --version # 需 ≥ 3.9 pip install python-okx --upgrade实盘测试网 flag 怎么切现象测试网 key 下单一直 401明明密钥是对的。根因flag 控制 x-simulated-trading 请求头0 是实盘、1 是测试网两边的密钥不能混用。# ❌ 忘了传 flag库默认 flag1测试网实盘 key 会打到测试网 client TradeAPI(api_keykey, api_secret_keysecret, passphrasepassphrase) # ✅ 测试网 key 配测试网 client TradeAPI(api_keykey, api_secret_keysecret, passphrasepassphrase, flag1) # ✅ 实盘flag0⚠️ flag 默认值是 1不传就是测试网。实盘 key 忘了传 flag 报 401这个坑我见过太多次了。401 / 403 三步排查现象私有接口全 401公共接口好好的。根因401 基本是密钥与 flag 环境不匹配或建密钥时没勾交易权限403 则是当前出口 IP 不在该密钥的白名单里。按环境匹配 → 权限 → IP 白名单三步走密钥从环境变量取而不是硬编码import os # ✅ 三件套从环境变量读确认同一账户、同一环境 api_key os.getenv(OKX_API_KEY) secret_key os.getenv(OKX_SECRET_KEY) passphrase os.getenv(OKX_PASSPHRASE) flag os.getenv(OKX_FLAG, 1) # ← 注意实盘要显式设 010000 签名验证失败先同步系统时间现象同一套 key官方 demo 能过我这边报 10000。根因签名是 timestamp 请求方法 请求路径 请求体的 HMAC-SHA256本地时钟和服务器偏差超过约 30 秒签名就验证失败。sudo ntpdate ntp.aliyun.com # ← 注意先同步系统时间再重试REST 调用参数精度与分页循环place_order 精度报错用 Decimal 修现象40000.123 这个价怎么就下单报错了根因每个交易对有最小价格精度和最小下单量BTC-USDT 的 tick 到不了 0.001服务器直接拒单。from decimal import Decimal # ❌ 裸 float精度超过 tick size trade.place_order(instIdBTC-USDT, tdModecash, sidebuy, ordTypelimit, px40000.123, sz0.001) # ✅ 用 Decimal小数位对齐合约精度 trade.place_order(instIdBTC-USDT, tdModecash, sidebuy, ordTypelimit, pxDecimal(40000.12), szDecimal(0.001))⚠️ float 的 0.1 0.2 等于 0.30000000000000004拿去做 px 就是参数错误常客。分页漏单循环写法现象拉历史订单怎么少了一半。根因单次最多返回 limit 条上限 100不循环传 after 游标就只拿到第一页。all_orders, after [], None while True: resp trade.get_orders_history(instTypeSPOT, afterafter, limit100) all_orders.extend(resp[data]) if len(resp[data]) 100: break after resp[data][-1][ordId] # ← 注意用本页最后一条 ordId 翻页WebSocket 实时通道1006 断连与心跳1006 断连30 秒心跳 5 秒重连现象跑了半小时连接就 code1006 断了。根因1006 是异常关闭多数是网络抖动或空闲超时少数是单连接订阅频道过多超流量上限。需要每 30 秒发一次 ping并在断线后 5 秒自动重连。ws WsPrivateAsync(api_key, passphrase, secret_key, ws_url) await ws.connect() await ws.subscribe([{channel: account}], on_msg) async def heartbeat(): while True: await asyncio.sleep(30) await ws.websocket.send(ping) # ← 注意每 30 秒发一次 asyncio.create_task(heartbeat()) # 心跳单独起任务 # 外层套 while True except 后 await asyncio.sleep(5) 即 5 秒重连⚠️ 私有频道和公共频道建议拆两条连接一条连接订阅过多是 1006 头号原因。测试网 WS 地址怎么写现象私有频道 login 一直失败。根因测试网和生产是两套 WebSocket 地址测试网在 wspap 子域下混用生产地址必然登录失败。# ❌ 生产地址 测试网 key url wss://ws.okx.com:8443/ws/v5/private # ✅ 测试网wspap 子域带 brokerId url wss://wspap.okx.com:8443/ws/v5/private?brokerId9999生产兜底异常捕获、限频与缓存三类异常分别捕获别让进程挂现象网络抖了一下策略进程直接没了。根因库抛三类异常——OkxAPIExceptionAPI 返回错误带 code/message、OkxRequestException网络层、OkxParamsException参数校验只捕第一种会漏掉后两类。from okx.exceptions import (OkxAPIException, OkxRequestException, OkxParamsException) try: trade.place_order(...) except OkxParamsException as e: print(f参数错误: {e.message}) except OkxAPIException as e: print(fAPI 错误: {e.code} - {e.message}) except OkxRequestException as e: # ← 注意网络错误才进重试队列 schedule_retry()429 限频加 100 毫秒 sleep现象批量下单第二单开始 429。根因每个接口有独立频控循环里裸调必撞限。串行场景每 0.1 秒一次把整体压在 10 次/秒以内。import time def rate_limited(trade, inst_id): time.sleep(0.1) # ← 注意保持 ≥100ms 间隔 return market.get_ticker(instIdinst_id)K 线本地缓存写法现象K 线接口被轮询打爆。根因K 线更新频率低每次渲染都请求是浪费额度加一层 lru_cache 即可。from functools import lru_cache lru_cache(maxsize100) def get_cached_candles(instId, bar): return market.get_candles(instIdinstId, barbar)本手册覆盖环境接入、鉴权、REST 调用、实时通道、生产兜底 4 个场景的常见故障。 上手可跑 example/get_started_en.ipynb回归看 test/unit/版本变更记录在 CHANGELOG.md。【免费下载链接】python-okx项目地址: https://gitcode.com/GitHub_Trending/py/python-okx创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考