保姆级教程：用Python的requests库搞定OKX V5 API现货/合约下单（含模拟盘设置）

Python实战：OKX V5 API全流程交易指南（含模拟盘与签名避坑）

最近在帮朋友搭建量化交易系统时，发现OKX的V5 API文档虽然全面，但实际接入过程中有几个关键细节容易踩坑。特别是签名生成和请求头构造部分，不同语言的实现差异可能导致莫名其妙的50113错误。本文将用最直白的方式，从密钥配置到完整下单，手把手带你跑通全流程。

1. 环境准备与密钥配置

在开始前，请确保已创建OKX账户并完成API密钥申请。登录OKX官网，进入"API管理"页面时，注意勾选"交易"权限，并妥善保存以下三组信息：

• API Key：形如aef0bf16-xxxx-xxxx-xxxx-xxxxxxxxxxxx
• Secret Key：32位随机字符串
• Passphrase：自定义的交易密码

推荐使用Python 3.8+环境，主要依赖库如下：

pip install requests python-dotenv

安全起见，建议将敏感信息存储在.env文件中：

# .env 示例 OKX_API_KEY=your_api_key OKX_SECRET_KEY=your_secret_key OKX_PASSPHRASE=your_password

通过环境变量加载配置更安全：

from dotenv import load_dotenv import os load_dotenv() API_KEY = os.getenv('OKX_API_KEY') SECRET_KEY = os.getenv('OKX_SECRET_KEY') PASSPHRASE = os.getenv('OKX_PASSPHRASE')

2. 签名生成的核心细节

签名(Sign)是API请求中最容易出错的环节。V5 API要求对以下要素进行HMAC-SHA256加密：

1. 时间戳（UTC格式，精确到毫秒）
2. HTTP方法（GET/POST等大写形式）
3. 请求路径（如/api/v5/trade/order）
4. 请求体（GET请求为空字符串）

关键实现要点：

import base64 import hmac from datetime import datetime def generate_signature(timestamp, method, path, body, secret_key): message = f"{timestamp}{method}{path}{body}" digest = hmac.new( bytes(secret_key, 'utf-8'), bytes(message, 'utf-8'), digestmod='sha256' ).digest() return base64.b64encode(digest).decode('utf-8') # bytes转str关键步骤

特别注意：Python的json.dumps()默认会在冒号/逗号后添加空格，而OKX的签名验证对此敏感。比较下面两种JSON格式：

# 默认生成（带空格） {"instId": "BTC-USDT", "tdMode": "cash"} # 紧凑模式（无空格） {"instId":"BTC-USDT","tdMode":"cash"}

虽然肉眼难辨，但签名结果完全不同。建议统一使用：

json.dumps(data, separators=(',', ':')) # 移除多余空格

3. 请求头构造与模拟交易

完整的请求头需要包含6个关键字段：

封装成请求构造器：

class OKXClient: BASE_URL = 'https://www.okx.com' def __init__(self, api_key, secret_key, passphrase): self.api_key = api_key self.secret_key = secret_key self.passphrase = passphrase def _get_headers(self, method, path, body=''): timestamp = datetime.utcnow().isoformat()[:-3] + 'Z' return { 'OK-ACCESS-KEY': self.api_key, 'OK-ACCESS-SIGN': generate_signature( timestamp, method, path, body, self.secret_key), 'OK-ACCESS-TIMESTAMP': timestamp, 'OK-ACCESS-PASSPHRASE': self.passphrase, 'Content-Type': 'application/json', 'x-simulated-trading': '1' # 1启用模拟盘，0为实盘 }

4. 现货与合约下单实战

4.1 市价单基础参数

不同交易品种的核心参数差异：

• 现货交易：

  • tdMode: cash（现金交易）
  • instId: 币对名称，如BTC-USDT

• 合约交易：

  • tdMode: cross（全仓）或isolated（逐仓）
  • instId: 合约名称，如BTC-USDT-SWAP

4.2 完整下单示例

import json def place_market_order(client, inst_id, side, amount, td_mode='cash'): path = '/api/v5/trade/order' url = f"{client.BASE_URL}{path}" body = json.dumps({ "instId": inst_id, "tdMode": td_mode, "side": side, # buy/sell "ordType": "market", "sz": str(amount) }, separators=(',', ':')) headers = client._get_headers('POST', path, body) response = requests.post(url, headers=headers, data=body) return response.json() # 使用示例 client = OKXClient(API_KEY, SECRET_KEY, PASSPHRASE) # 现货市价买入0.01 BTC print(place_market_order( client, inst_id="BTC-USDT", side="buy", amount=0.01 )) # 合约全仓市价卖出1 BTC print(place_market_order( client, inst_id="BTC-USDT-SWAP", side="sell", amount=1, td_mode="cross" ))

4.3 常见错误排查

当遇到50113 Invalid Sign错误时，建议按以下顺序检查：

1. 时间戳是否同步（误差需在30秒内）
2. JSON体是否按字母顺序排序
3. 冒号/逗号后是否有空格
4. 签名前的字符串拼接顺序是否正确
5. Secret Key是否包含特殊字符需要转义

一个实用的调试技巧是打印出签名前的原始消息：

print(f"Signing message: {timestamp}{method}{path}{body}")

5. 高级功能扩展

5.1 批量下单

通过/api/v5/trade/batch-orders接口，单次最多可提交20个订单：

orders = [ {"instId": "BTC-USDT", "side": "buy", "sz": "0.01"}, {"instId": "ETH-USDT", "side": "sell", "sz": "0.1"} ] body = json.dumps(orders, separators=(',', ':'))

5.2 条件单触发

设置止损止盈订单示例：

{ "instId": "BTC-USDT-SWAP", "tdMode": "cross", "side": "sell", "ordType": "trigger", "triggerPx": "50000", # 触发价格 "orderPx": "-1", # -1表示市价 "sz": "1" }

5.3 资金费率套利

结合/api/v5/public/funding-rate接口查询费率：

def get_funding_rate(client, inst_id): path = f'/api/v5/public/funding-rate?instId={inst_id}' headers = client._get_headers('GET', path) return requests.get(f"{client.BASE_URL}{path}", headers=headers).json()

在实盘切换前，强烈建议先用模拟盘验证策略。记得在测试完成后将x-simulated-trading头改为0，否则所有请求将继续发送到模拟环境。