示例参数

OKX合约开发入门到实践：打造你的量化交易利器**

---

OKX（原OKEx）作为全球领先的数字资产交易平台，为开发者提供了强大的API接口和合约

交易功能，使得构建自动化、程序化的合约交易策略成为可能，本教程将带你从零开始，逐步了解并掌握OKX合约开发的核心知识与实操步骤，助你迈出量化交易策略开发的第一步。

OKX合约开发概览

在开始之前,我们需要明确几个核心概念：

1. 合约类型：OKX支持U本位合约、币本位合约以及期权合约，本教程将以更普遍的U本位合约为例进行讲解，但其核心逻辑同样适用于币本位合约。
2. 交易模式：包括限价单（Limit）、市价单（Market）、止盈止损单（Take Profit/Stop Loss）等。
3. API接口：OKX提供RESTful API和WebSocket API，RESTful API适合执行一次性操作（如下单、查询），WebSocket API则适合实时获取行情数据和账户信息，对实时性要求高的策略（如高频交易、套利）至关重要。

开发前的准备

1. 注册OKX账户并完成认证：
   • 访问OKX官网（www.okx.com）完成注册。
   • 实名认证是使用API的前提,确保账户状态正常。
2. 创建API Key：
   • 登录OKX账户,进入【账户】->【API管理】。
   • 创建一个新的API Key，设置IP访问白名单（为了安全，建议限制为开发服务器IP）。
   • 务必妥善保管你的API Key Secret和Passphrase（如果设置了），切勿泄露。
   • 根据需求勾选相应的权限,如“读取”、“交易”（下单、撤单等）、“合约交易”等，为了开发初期安全，建议先给予最小必要权限。
3. 选择开发工具与环境：
   • 编程语言：Python是量化开发的主流选择，拥有丰富的库（如requests, websockets, pandas, numpy）和活跃的社区，本教程将以Python为例。
   • IDE/编辑器：PyCharm, VS Code等。
   • 网络环境：确保网络稳定，部分API请求可能需要配置代理（OKX提供不同区域的API endpoint）。

核心API接口详解与实践

身份认证

所有API请求都需要进行身份认证,OKX使用API Key、Secret和Passphrase（如果创建时设置）进行HMAC-SHA256签名。

签名步骤简述：

1. 构造请求体（对于GET请求，可能是查询字符串；对于POST/PUT/DELETE请求，是请求体）。
2. 生成一个时间戳（ISO 8601格式）。
3. 将HTTP方法、请求路径、时间戳、请求体（如果有）按特定顺序拼接。
4. 使用API Secret对拼接后的字符串进行HMAC-SHA256加密，生成签名。
5. 将API Key、时间戳、签名等信息放在请求头中发送。

Python示例（生成签名）：

import hmac
import base64
import json
from datetime import datetime
import hashlib
def sign(method, request_path, body, secret_key):
    timestamp = datetime.utcnow().isoformat(timespec='milliseconds') + 'Z'
    message = f'{timestamp}{method}{request_path}{body}' if body else f'{timestamp}{method}{request_path}'
    signature = base64.b64encode(
        hmac.new(secret_key.encode('utf-8'), message.encode('utf-8'), digestmod=hashlib.sha256).digest()
    ).decode()
    return timestamp, signature
api_key = 'YOUR_API_KEY'
secret_key = 'YOUR_SECRET_KEY'
passphrase = 'YOUR_PASSPHRASE'  # 如果设置了
method = 'GET'
request_path = '/api/v5/market/ticker?instId=BTC-USDT-SWAP'
body = ''
timestamp, signature = sign(method, request_path, body, secret_key)
# 请求头
headers = {
    'OK-ACCESS-KEY': api_key,
    'OK-ACCESS-SIGN': signature,
    'OK-ACCESS-TIMESTAMP': timestamp,
    'OK-ACCESS-PASSPHRASE': passphrase,
    'Content-Type': 'application/json'
}

获取合约市场数据

这是开发策略的基础,包括K线数据、深度数据、最新价格等。

• 获取K线数据：GET /api/v5/market/candles
  • 参数：instId（产品ID，如BTC-USDT-SWAP）、bar（K线周期，如1m, 5m, 1H, 1D）、before/after/limit（可选，用于分页）。
• 获取深度数据：GET /api/v5/market/books
  • 参数：instId、sz（深度档位数）。
• 获取最新价格：GET /api/v5/market/ticker
  • 参数：instId。

Python示例（获取K线数据）：

import requests
def get_kline_data(inst_id, bar='1H', limit=100):
    url = 'https://www.okx.com/api/v5/market/candles'
    params = {
        'instId': inst_id,
        'bar': bar,
        'limit': limit
    }
    headers = {
        'Content-Type': 'application/json'
        # 此处无需认证的公开接口，但有些市场数据可能需要
    }
    try:
        response = requests.get(url, params=params, headers=headers)
        response.raise_for_status()
        return response.json()
    except requests.exceptions.RequestException as e:
        print(f"Error fetching kline data: {e}")
        return None
kline_data = get_kline_data('BTC-USDT-SWAP')
if kline_data and kline_data['code'] == '0':
    print("K-line data:", kline_data['data'])
else:
    print("Failed to fetch kline data:", kline_data.get('msg'))

账户信息查询

• 获取账户资产：GET /api/v5/account/balance

  需要认证。

• 获取持仓信息：GET /api/v5/account/positions

  需要认证。

合约交易操作

这是合约开发的核心,包括下单、撤单、查询订单等。

• 下单：POST /api/v5/trade/order
  • 参数：instId（产品ID）、tdMode（交易模式，如cross全仓，isolated逐仓）、side（buy/sell）、ordType（订单类型，如limit限价，market市价）、sz（下单数量）、px（限价单价格，市价单无需）等。
• 撤单：POST /api/v5/trade/cancel-order
  • 参数：instId、ordId（订单ID）。
• 查询订单信息：GET /api/v5/trade/order
  • 参数：instId、ordId或clOrdId（客户端订单ID）。

Python示例（下单）：

def place_order(inst_id, side, sz, ord_type='limit', px=None, td_mode='cross'):
    url = 'https://www.okx.com/api/v5/trade/order'
    params = {
        'instId': inst_id,
        'tdMode': td_mode,
        'side': side,
        'ordType': ord_type,
        'sz': sz
    }
    if ord_type == 'limit' and px:
        params['px'] = px
    # 使用前面构造的headers（包含认证信息）
    try:
        response = requests.post(url, json=params, headers=headers)
        response.raise_for_status()
        return response.json()
    except requests.exceptions.RequestException as e:
        print(f"Error placing order: {e}")
        return None
# 示例：下限价买单
order_result = place_order(
    inst_id='BTC-USDT-SWAP',
    side='buy',
    sz='0.001',  # 买卖0.1 BTC合约
    ord_type='limit',
    px='30000',  # 假设现价30000，挂单30000
    td_mode='cross'
)
if order_result and order_result['code'] == '0':
    print("Order placed successfully, ordId:", order_result['data'][0]['ordId'])
else:
    print("Failed to place order:", order_result.get('msg'))

WebSocket 实时数据接入（