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

选择API接口类型

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

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

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

理解API请求与认证机制

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

1. 请求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（下单）等。

2. 请求方法：常用的有GET（获取数据）、POST（提交数据，如下单）、DELETE（删除数据，如取消订单）。

3. 请求头（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

4. 签名生成（关键步骤）： 签名是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等替换为您的实际信息，并使用正确的请求头）：

1. 获取合约行情信息（如BTC-USDT合约的最新价格）：

   • Endpoint: GET /api/v5/market/ticker
   • Parameters: instId=BTC-USDT-SWAP (指定合约ID)
   • 无需认证：此为公开数据接口。

2. 获取账户资产：

   • Endpoint: GET /api/v5/account/balance
   • 需要认证：使用前面提到的请求头。

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

   • 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空仓（某些合约或模式下需要）
     }

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

4. 查询订单状态：

   • Endpoint: GET /api/v5/trade/order
   • Parameters: instId=BTC-USDT-SWAP, ordId=YOUR_ORDER_ID

5. 取消订单：

   • Endpoint: POST /api/v5/trade/cancel-order
   • Parameters (JSON Body):

     {
         "instId": "BTC-USDT-SWAP",
         "ordId": "YOUR_ORDER_ID"
     }

错误处理与调试

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

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