API 教程(一) V5 API交易与申请
想要实现自动化交易、开发交易机器人，或者将OKX的交易功能集成到自己的应用中？OKX V5 API是你的最佳选择。2024年数据显示，通过API进行的交易量占OKX总交易量的65%以上，专业交易者和量化团队都在使用API提升交易效率。
前置要求：基础的编程知识（Python、JavaScript或其他语言）
什么是OKX V5 API？
OKX V5 API是OKX交易所提供的第五代应用程序接口，允许开发者通过编程方式访问交易所的各项功能。
V5 API的核心优势
统一账户架构
V5 API采用统一账户模式，一个账户可以同时交易现货、合约、期权等多种产品，资金自动共享，无需频繁划转。
更高的性能
- REST API响应时间：平均50ms
- WebSocket推送延迟：<10ms
- 支持批量操作：单次最多20个订单
更完善的功能
- 支持所有交易类型：现货、杠杆、合约、期权
- 实时行情推送：K线、深度、成交数据
- 账户管理：资产查询、持仓管理、历史记录
- 策略交易：网格、定投、冰山委托等
V5 vs V3：为什么要升级？
| 功能 | V3 API | V5 API | |------|--------|--------| | 账户模式 | 分离账户 | 统一账户 | | 产品支持 | 部分产品 | 全产品线 | | 性能 | 标准 | 提升50% | | WebSocket | 单向推送 | 双向通信 | | 文档 | 基础 | 详细+示例 |
申请API密钥：5分钟完成
第一步：登录OKX账户
访问 OKX官网，登录你的账户。如果还没有账户，需要先完成注册和KYC认证。
安全建议：
- 启用双重认证（2FA）
- 设置资金密码
- 绑定手机和邮箱
第二步：进入API管理页面
- 点击右上角头像
- 选择”API”菜单
- 点击”创建V5 API密钥”
第三步：配置API权限
权限类型：
只读权限（Read）
- 查询账户资产
- 查询订单历史
- 查询持仓信息
- 适合：数据分析、监控工具
交易权限（Trade）
- 下单、撤单
- 修改订单
- 批量操作
- 适合：交易机器人、自动化策略
提现权限（Withdraw）
- 提币到外部地址
- 内部转账
- 风险最高，谨慎开启
推荐配置：
- 初学者：只开启”只读”权限
- 交易机器人：开启”只读+交易”权限
- 提现功能：单独创建专用API，设置IP白名单
第四步：设置IP白名单（强烈推荐）
IP白名单可以限制只有指定IP才能使用API，大幅提升安全性。
如何获取你的IP地址：
# Linux/Mac
curl ifconfig.me
# Windows PowerShell
(Invoke-WebRequest -Uri “https://api.ipify.org”).Content
配置建议：
- 固定IP服务器：添加服务器IP
- 动态IP：使用VPS或云服务器
- 多个IP：用逗号分隔，最多20个
第五步：保存API密钥
创建成功后，系统会显示三个关键信息：
API Key（公钥）
示例：a1b2c3d4-e5f6-7890-abcd-ef1234567890
用途：标识你的API身份
Secret Key（私钥）
示例：1A2B3C4D5E6F7890ABCDEF1234567890
用途：签名请求，证明请求来自你
Passphrase（口令）
示例：MySecurePass123!
用途：额外的安全验证
安全存储建议：
- 使用密码管理器（如1Password、LastPass）
- 不要存储在代码仓库中
- 不要通过邮件或聊天工具发送
- 定期更换（建议每3个月）
如果Secret Key泄露：
- 立即删除该API密钥
- 创建新的API密钥
- 检查账户是否有异常交易
- 修改账户密码和资金密码
第一个API请求：查询账户余额
让我们用Python发起第一个API请求，查询账户余额。
安装依赖
pip install requests
完整代码示例
import requests
import hmac
import base64
import time
from datetime import datetime
# API配置（替换为你的密钥）
API_KEY = “your-api-key”
SECRET_KEY = “your-secret-key”
PASSPHRASE = “your-passphrase”
BASE_URL = “https://www.okx.com”
def generate_signature(timestamp, method, request_path, body=''):
“””生成签名”””
message = timestamp + method + request_path + body
mac = hmac.new(
bytes(SECRET_KEY, encoding='utf8'),
bytes(message, encoding='utf-8'),
digestmod='sha256'
)
return base64.b64encode(mac.digest()).decode()
def get_account_balance():
“””查询账户余额”””
# 请求参数
method = “GET”
request_path = “/api/v5/account/balance”
# 生成时间戳（ISO 8601格式）
timestamp = datetime.utcnow().isoformat(timespec='milliseconds') + 'Z'
# 生成签名
signature = generate_signature(timestamp, method, request_path)
# 构建请求头
headers = {
“OK-ACCESS-KEY”: API_KEY,
“OK-ACCESS-SIGN”: signature,
“OK-ACCESS-TIMESTAMP”: timestamp,
“OK-ACCESS-PASSPHRASE”: PASSPHRASE,
“Content-Type”: “application/json”
}
# 发送请求
response = requests.get(BASE_URL + request_path, headers=headers)
# 解析响应
if response.status_code == 200:
data = response.json()
if data['code'] == '0':
print(“账户余额：”)
for detail in data['data'][0]['details']:
if float(detail['availBal']) > 0:
print(f”{detail['ccy']}: {detail['availBal']}”)
else:
print(f”错误：{data['msg']}”)
else:
print(f”请求失败：{response.status_code}”)
# 执行查询
get_account_balance()
代码详解
签名生成过程：
- 拼接字符串：
timestamp + method + request_path + body - 使用HMAC-SHA256算法，用Secret Key对字符串加密
- 将结果进行Base64编码
为什么需要签名？
签名机制确保：
- 请求确实来自你（拥有Secret Key）
- 请求内容未被篡改
- 请求是最近发起的（防止重放攻击）
时间戳要求：
- 必须是UTC时间
- 格式：ISO 8601（如
2024-04-07T12:30:45.123Z） - 与服务器时间差不能超过30秒
运行结果
账户余额：
USDT: 1000.5
BTC: 0.05
ETH: 1.2
常见错误及解决方案
错误1：签名验证失败
{
“code”: “50113”,
“msg”: “Invalid sign”
}
原因：
- Secret Key错误
- 签名算法实现有误
- 时间戳格式不正确
解决方案：
- 检查Secret Key是否正确复制（注意空格）
- 确保时间戳是UTC时间
- 参考官方SDK示例代码
错误2：时间戳过期
{
“code”: “50102”,
“msg”: “Timestamp request expired”
}
原因：
- 本地时间与服务器时间差超过30秒
解决方案：
# Linux/Mac同步时间
sudo ntpdate -u time.apple.com
# Windows
w32tm /resync
错误3：IP不在白名单
{
“code”: “50111”,
“msg”: “Invalid IP”
}
原因：
- 请求IP不在API白名单中
解决方案：
- 在API管理页面添加当前IP
- 或者删除IP白名单限制（不推荐）
错误4：权限不足
{
“code”: “50004”,
“msg”: “Endpoint requires authentication”
}
原因：
- API密钥没有相应权限
解决方案：
- 在API管理页面修改权限设置
- 或创建新的API密钥并授予所需权限
下一步学习
恭喜你完成了第一个API请求！接下来可以学习：
教程二：交互式浏览器使用方法
学习如何使用OKX提供的API测试工具，无需编程即可测试所有API接口。
教程三：WebSocket API实时行情
学习如何通过WebSocket获取实时行情数据，延迟低至10ms。
教程四：获取个人数据
学习如何查询订单历史、持仓信息、资金流水等个人数据。
进阶教程：
实用资源
官方文档：
开发工具：
社区支持：
API技术支持邮箱：[email protected]
总结
本教程介绍了OKX V5 API的基础知识和申请流程：
关键要点：
- V5 API采用统一账户架构，性能提升50%
- 申请API需要设置权限和IP白名单
- API密钥包含三部分：API Key、Secret Key、Passphrase
- 所有请求都需要HMAC-SHA256签名验证
- 时间戳必须是UTC时间，与服务器时差<30秒
安全建议：
- 使用IP白名单限制访问
- 定期更换API密钥
- 不同用途使用不同API密钥
- 妥善保管Secret Key
下一步： 继续学习本系列教程，掌握API的高级用法，开发你的第一个交易机器人！
免责声明
本文章可能包含不适用于您所在地区的产品相关内容。本文仅致力于提供一般性信息，不对其中的任何事实错误或遗漏负责任。本文仅代表作者个人观点，不代表欧易的观点。 本文无意提供以下任何建议，包括但不限于：(i) 投资建议或投资推荐；(ii) 购买、出售或持有数字资产的要约或招揽；或 (iii) 财务、会计、法律或税务建议。 持有的数字资产 (包括稳定币) 涉及高风险，可能会大幅波动，甚至变得毫无价值。您应根据自己的财务状况仔细考虑交易或持有数字资产是否适合您。有关您具体情况的问题，请咨询您的法律/税务/投资专业人士。本文中出现的信息 (包括市场数据和统计信息，如果有) 仅供一般参考之用。尽管我们在准备这些数据和图表时已采取了所有合理的谨慎措施，但对于此处表达的任何事实错误或遗漏，我们不承担任何责任。 © 2025 OKX。本文可以全文复制或分发，也可以使用本文 100 字或更少的摘录，前提是此类使用是非商业性的。整篇文章的任何复制或分发亦必须突出说明：”本文版权所有 © 2025 OKX，经许可使用。”允许的摘录必须引用文章名称并包含出处，例如”文章名称，[作者姓名 (如适用)]，© 2025 OKX”。部分内容可能由人工智能（AI）工具生成或辅助生成。不允许对本文进行衍生作品或其他用途。
