OKEx合约API接入全攻略,从申请到实战交易

投稿 2026-03-03 21:57 点击数： 1

OKEx作为全球领先的数字资产交易平台,其合约交易功能为用户提供了丰富的投资机会和风险管理工具，通过接入OKEx合约API，开发者可以实现程序化交易、自动化策略执行、数据获取等功能，极大地提升交易效率和灵活性，本文将详细介绍如何一步步接入OKEx合约API，助您快速开启程序化合约交易之旅。

准备工作：API接入的前置条件

在开始接入API之前,请确保您已完成以下准备工作：

注册OKEx账户：如果您还没有OKEx账户，请先前往OKEx官网完成注册，并通过身份验证（KYC）。
开通合约交易权限：在OKEx平台，确保您已开通合约交易功能，并了解相关交易规则和风险。
获取API Key：
- 登录OKEx账户,进入“API管理”页面。
- 点击“创建API”，您需要为API设置一个名称（便于识别），并选择权限。对于合约交易，您通常需要选择“交易”权限，以及具体的合约交易对权限（如全合约权限或指定交易对）。
- 重要：创建成功后，系统会生成唯一的API Key、Secret Key和Passphrase（Passphrase是您在创建API时设置的，请务必妥善保管，此信息在后续创建API时不会再次显示）。
- 安全提示：请勿将您的API Key、Secret Key和Passphrase泄露给他人，并建议定期更换，IP白名单功能可以进一步增强安全性，建议在“API管理”中设置您常用的IP地址。

选择API接口类型

OKEx提供了多种API接口以满足不同需求：

REST API：最常用的API类型，适用于请求-响应模式，适合获取数据（如行情、账户信息）、执行交易（如下单、查询订单）、管理账户等操作，本文将主要围绕REST API展开。
WebSocket API：基于事件驱动的实时数据推送接口，适合需要实时获取行情数据（如K线、深度、成交）、订单状态更新等场景，能显著降低延迟，提升数据获取效率。
FIX API：金融信息交换协议，为专业机构和高频交易者提供更稳定、低延迟的交易接入。

对于大多数普通开发者和程序化交易者而言,REST API和WebSocket API是核心，我们先从REST API入手。

理解API请求与认证机制

OKEx REST API的请求需要遵循特定的规则和认证方式：

请求URL：OKEx提供了测试网和主网API地址。强烈建议您在开发测试阶段先使用测试网，确认无误后再切换到主网。
- 测试网API Base URL: https://www.okex.com/api/v5
- 主网API Base URL: https://www.okex.com/api/v5 (请注意查看OKEx官方文档，确保URL正确，可能会有调整)
- 合约相关的API通常会有特定的路径,如 /market/ticker（行情）、/trade/order（下单）等。
请求方法：常用的有GET（获取数据）、POST（提交数据，如下单）、DELETE（删除数据，如取消订单）。
请求头（Headers）：
- OK-ACCESS-KEY: 您的API Key
- OK-ACCESS-SIGN: 签名（用于验证请求的合法性和完整性）
- OK-ACCESS-TIMESTAMP: 请求时间戳（UTC时间，格式如：2023-01-01T00:00:00.000Z）
- OK-ACCESS-PASSPHRASE: 您的API Passphrase
- Content-Type: 请求内容类型，如application/json或application/x-www-form-urlencoded

签名生成（关键步骤）：签名是API安全的核心，OKEx使用HMAC-SHA256算法生成签名。

步骤：
1. 创建一个待签名字符串：timestamp + method + requestPath + body（注意：method为大写，requestPath为不包含域名和查询参数的路径，body为POST/PUT请求的请求体，GET请求的body为空字符串）。
2. 使用您的Secret Key对上述待签名字符串进行HMAC-SHA256加密。
3. 将加密结果进行Base64编码,得到的字符串即为OK-ACCESS-SIGN。

示例代码（Python）：

import hmac
import base64
import hashlib
import time
api_key = "YOUR_API_KEY"
secret_key = "YOUR_SECRET_KEY".encode('utf-8')
passphrase = "YOUR_PASSPHRASE"
timestamp = time.strftime("%Y-%m-%dT%H:%M:%S.000Z", time.gmtime())
method = "GET"  # 或 POST, DELETE 等
request_path = "/api/v5/market/ticker?instId=BTC-USDT-SWAP"  # 示例路径
body = ""  # GET请求body为空
# 构建待签名字符串
sign_string = f"{timestamp}{method}{request_path}{body}".encode('utf-8')
# 生成签名
signature = base64.b64encode(hmac.new(secret_key, sign_string, digestmod=hashlib.sha256).digest()).decode('utf-8')
# 在请求头中使用
headers = {
    "OK-ACCESS-KEY": api_key,
    "OK-ACCESS-SIGN": signature,
    "OK-ACCESS-TIMESTAMP": timestamp,
    "OK-ACCESS-PASSPHRASE": passphrase,
    "Content-Type": "application/json"
}

合约API常见操作示例

OKEx合约API非常丰富,以下列举几个常用操作的REST API示例（请将YOUR_API_KEY等替换为您的实际信息，并使用正确的请求头）：

获取合约行情信息（如BTC-USDT合约的最新价格）：
- Endpoint: GET /api/v5/market/ticker
- Parameters: instId=BTC-USDT-SWAP (指定合约ID)
- 无需认证：此为公开数据接口。
获取账户资产：
- Endpoint: GET /api/v5/account/balance
- 需要认证：使用前面提到的请求头。

下单（开多/开空/平多/平空）：

Endpoint: POST /api/v5/trade/order

Parameters (JSON Body):

{
    "instId": "BTC-USDT-SWAP", // 合约ID
    "tdMode": "cross", // 全仓模式：cross，逐仓模式：isolated
    "side": "buy", // buy 或 sell
    "ordType": "limit", // limit 限价, market 市价
    "sz": "10", // 委托数量
    "px": "30000", // 限价价格（市价单无需此字段）
    "tdMode": "cross", // 交易模式：cross全仓，isolated逐仓
    "posSide": "long" // 持仓方向：long多仓，short空仓（某些合约或模式下需要）
}

需要认证：此为私有数据接口，需要严格认证。

查询订单状态：
- Endpoint: GET /api/v5/trade/order
- Parameters: instId=BTC-USDT-SWAP, ordId=YOUR_ORDER_ID
取消订单：
- Endpoint: POST /api/v5/trade/cancel-order
- Parameters (JSON Body)
  :
```
{
    "instId": "BTC-USDT-SWAP",
    "ordId": "YOUR_ORDER_ID"
}
```

错误处理与调试

在API接入过程中,遇到错误是常有的事，OKEx API返回的错误信息通常会包含code（错误码）和msg（错误描述），请务必：

仔细阅读OKEx官方API文档：这是最权威的信息来源，包含了所有接口的详细说明、参数、错误码等。
检查请求头：确保API Key、Secret Key、Passphrase正确，Timestamp格式正确且与服务器时间同步（过大或过小的时间戳会导致签名错误）。
检查请求参数：确保参数名称、格式、取值范围符合API文档要求。

OKEx合约API接入全攻略,从申请到实战交易

最近发表

文章推荐