★ FEATURED ARTICLE 简介基于OKX平台的自动化量化交易框架源码包面向加密货币量化交易开发者尤其适合已有C#基础、希望对接OKX API并搭建完整自动交易系统的工程师。资源围绕策略开发、交易执行、资金管理与风险控制等模块展开包含行情获取、订单管理和止损止盈等可扩展逻辑能帮助读者理解量化框架的工程化落地方式。压缩包共318个文件约452KB以256个C#源码文件为主搭配35个资源文件、8个配置文件以及解决方案/项目文件构成一套结构清晰的Visual Studio解决方案。另有说明文档、授权许可以及证书等文件便于阅读和二次开发。该资源已有84人学习浏览适合用于参考OKX平台API调用方式、理解量化交易程序的模块划分在此基础上改造为自有策略或接入更多交易功能。整体包体精简代码密度较高是学习交易所API量化开发的一份实用素材。1. 先判断它值不值得下这不是挂个机器人是一套 API 工程先说结论这份基于 OKX 平台的自动化量化交易框架 zip解压后不是那种“一键启动、自动赚钱”的黑匣子而是一套能连上 OKX V5 接口的 Python 交易工程。它的核心价值是把行情拉取、策略信号、下单、持仓管理这几件事用代码串起来。你不需要从零去啃 API 文档但至少要看得懂 Python 基础。它适合手里已经有一套自己的策略、或者想研究“交易所接口到底怎么调”的人。打开 zip 之前先想清楚程序只能替你执行规则不能替你创造规则规则没想好跑实盘大概率翻车。这也是为什么我先讲工程结构再带你把配置、下单、回测、上实盘走通。2. 解压后的项目结构先分清五个模块再谈“能不能跑”2.1 目录分层交易代码和策略代码为什么必须分开把 zip 解压后最先看到的不是一堆 .py 堆在一起而是按模块分好的目录。我的习惯是先看目录如果交易逻辑和策略逻辑混在同一层这个框架后面改起来会非常痛苦。常见的分层是 exchange、strategy、risk、data、config 五块各自负责一件事。quant_okx/ ├── config/ │ ├── config.yaml │ └── secrets.example.yaml ├── exchange/ │ ├── rest.py │ └── ws.py ├── strategy/ │ ├── base.py │ └── ma_cross.py ├── risk/ │ ├── position.py │ └── stop_loss.py ├── data/ │ └── kline.py └── main.py这么拆的原因很直接策略换参数、换指标是高频动作而交易所接口调整是低频动作。如果 strategy 层的代码直接写了 requests.post每次调交易所接口都要改策略文件回测也没法跑。exchange 层只负责“发单、撤单、查余额”strategy 层只负责“根据 K 线返回买/卖/不动”risk 层只负责“下几单、止损在哪里”。这样以后想换模拟盘、实盘或者换交易对改动范围都被圈住。实际操作中你会发现主循环 main.py 往往很短真正的复杂度都被分摊到这些模块里了。另外config 下通常会有 secrets.example.yaml 模板真实密钥不要提交到 git 里。如果项目根目录有.gitignore把secrets*.yaml、config.yaml如果里面写了真实 key加进去。密钥被推到公开仓库等于把账户控制权交出去这也是很多开源框架被“扫库”的直接原因。拿到 zip 后先复制模板再填值我一般用cp config/secrets.example.yaml config/secrets.yaml让模板和真实配置分开。2.2 环境安装Python 3.10 venv requirements.txt先把环境跑起来。这个框架依赖 requests、websocket-client、pandas、pyyaml推荐直接用虚拟环境隔离不要把包装到系统 Python 里。命令行如下cd quant_okx python3 -m venv venv source venv/bin/activate # Windows 用 venv\Scripts\activate pip install --upgrade pip pip install -r requirements.txt如果你所在网络环境 pip 很慢可以临时指定国内镜像源加一行-i https://pypi.tuna.tsinghua.edu.cn/simple但这只影响下载速度不影响后续运行。装完之后用pip list确认 websocket-client 版本不是太老我建议至少 1.4 以上旧版本在处理 ping/pong 时偶尔会卡住。Python 版本方面3.8 也能跑但 3.10 更省心因为部分代码用了str | None这类新式类型标注低于 3.10 会报语法错误。如果你拿到的是老代码需要把类型标注改成 Optional 才能兼容。2.3 配置文件API Key、Passphrase、模拟盘开关框架能跑通一半功劳在配置。第一次拿到 zip先改配置文件不要先改策略。下面这份 yaml 基本覆盖了大多数常用场景# config.yaml env: demo # demo 模拟盘 / live 实盘 api: key: your-api-key secret: your-secret passphrase: your-passphrase trade: inst_id: BTC-USDT-SWAP td_mode: isolated # isolated 逐仓 / cross 全仓 leverage: 3 max_notional_usd: 300 # 单仓名义价值上限 strategy: fast_ma: 5 slow_ma: 20 stop_loss_pct: 0.05这里有几个容易出错的地方。passphrase 不是登录密码是创建 API Key 的时候自己填的口令签名认证会用填错的话所有请求都返回 50113。模拟盘也不是只靠env: demo这个字段OKX 的模拟盘请求带一个特殊 headerx-simulated-trading: 1框架内部会根据 env 自动加上。创建 API Key 的时候权限最少勾上“读取”和“交易”如果只勾读取后面下单会报错 60010。另外td_mode: isolated表示逐仓意思是一个合约的爆仓不会拖垮账户里其他币的保证金新人建议先逐仓、低杠杆跑。max_notional_usd是名义价值上限不是下单的 USDT 数量后面第 4 章会讲这个换算。2.4 启动入口先跑“自检函数”再进主循环不要把 main.py 直接扔到机器上就跑。我会先做一个 health_check检查账户能不能访问、杠杆能不能设置、配置里的交易对是否存在。# main.py 启动顺序 import toml # 或 yaml from exchange.okx_rest import OkxRest cfg load_config(config/config.yaml) def health_check(api: OkxRest, cfg: dict): balance api.get_balance() if float(balance.get(totalEq, 0)) 0: raise RuntimeError(账户余额为0请检查API权限或模拟盘开关) api.set_leverage( instIdcfg[trade][inst_id], levercfg[trade][leverage], mgnModecfg[trade][td_mode], ) print(自检通过进入主循环)这个函数的逻辑很简单先确认账户能查到余额再确认杠杆设置成功。很多“上线后才发现问题”的案例都是因为在主循环里直接从某根 K 线开始下单但账户没有模拟盘权限或者杠杆没有设置导致仓位和预期完全对不上。把自检函数放在最前面等于给了自己一次后悔药。注意set_leverage 必须在开仓之前调用尤其逐仓模式下从默认杠杆改成指定杠杆要花一次单独的请求。3. 行情与下单链路REST 轮询 WebSocket 订阅为什么这样配先说明为什么要 REST 又要 WebSocketREST 适合“低频、需要确认结果”的操作比如查余额、下单、查单一次请求一个响应结果明确。WebSocket 适合“高频、需要被动接收”的数据比如订单成交推送、持仓变化不用反复轮询。量化框架里两者会同时出现REST 负责发指令WebSocket 负责接收交易所主动推回来的状态。3.1 签名方法所有请求的“身份证”怎么算OKX 所有私有接口都要签名签名的目的是让交易所知道这个请求确实来自你的 API Key。签名规则是timestamp method requestPath body用 HMAC-SHA256 加盐后做 base64。import time import json import hmac import hashlib import base64 def make_signature(secret_key: str, timestamp: str, method: str, request_path: str, body: str) - str: message timestamp method request_path body mac hmac.new( secret_key.encode(utf-8), message.encode(utf-8), hashlib.sha256, ) return base64.b64encode(mac.digest()).decode(utf-8) def build_headers(api_key: str, secret_key: str, passphrase: str, method: str, request_path: str, body: str ) - dict: timestamp str(int(time.time() * 1000)) # 毫秒时间戳 sign make_signature(secret_key, timestamp, method, request_path, body) return { OK-ACCESS-KEY: api_key, OK-ACCESS-SIGN: sign, OK-ACCESS-TIMESTAMP: timestamp, OK-ACCESS-PASSPHRASE: passphrase, Content-Type: application/json, }这里最容易踩的坑是 body 的格式。json.dumps(body)是什么样签名里就是什么样不能先json.loads再拼接否则字符顺序一变签名就校验失败。GET 请求没有 body传空字符串POST 请求如果带 query string比如带订单 ID 查单requestPath 要包含 query 部分比如/api/v5/trade/order?instIdBTC-USDT-SWAPordId123。timestamp 用毫秒时间戳header 里的 timestamp、签名里的 timestamp 必须是同一个字符串很多人分开生成两次导致偶发报错 50111。3.2 REST 下单请求体里的核心参数有了签名下单就顺理成章。REST 下单接口是/api/v5/trade/order一次请求下一笔单响应里返回交易所的订单号。import requests import json base https://www.okx.com path /api/v5/trade/order body { instId: BTC-USDT-SWAP, tdMode: isolated, side: buy, ordType: limit, px: 65000.0, sz: 1, clOrdId: ma_cross_001, } headers build_headers(api_key, secret_key, passphrase, POST, path, json.dumps(body)) headers[Content-Type] application/json if cfg[env] demo: headers[x-simulated-trading] 1 resp requests.post(base path, headersheaders, jsonbody, timeout5) data resp.json() if data.get(code) 0: print(委托成功, data[data][0][ordId]) else: print(下单失败, data[code], data[msg])逐个说参数instId必须是标准合约 ID永续合约长这样BTC-USDT-SWAP现货是BTC-USDT写错会直接报错。tdMode是逐仓还是全仓逐仓下每个合约单独管理保证金风险隔离。side是 buy 或 sell单向持仓模式下平多就是 sell平空就是 buy。ordType常用限定单、市价单、只做 maker 单post_only如果会立即成交就自动撤销适合做市商策略fok是全部成交否则撤单ioc是立即成交部分剩余撤单。普通限价单用limit就行。px和sz都是字符串不要传浮点数合约的sz单位是张不是币BTC-USDT-SWAP一张等于 0.01 BTC。clOrdId是客户端自定的订单号建议每次都生成唯一值后面查单、对账都靠它。下单响应只代表交易所收下了这张单不代表已经成交。所以框架里不要看到code:0就更新本地持仓还得看 WebSocket 推送的成交回报。3.3 查单和对账别把下单响应当成最终结果如果网络抖动POST 请求超时但交易所实际可能已经接单了。这时候本地以为没发出去再重发一次就会重复下单。查单接口就是来解决这个问题的。# 查询订单状态 path /api/v5/trade/order?instIdBTC-USDT-SWAPordId1234567890 headers build_headers(api_key, secret_key, passphrase, GET, path, ) resp requests.get(base path, headersheaders, timeout5) order resp.json()[data][0] print(order.get(state)) # live / filled / canceled print(order.get(accFillSz), order.get(avgPx))state几个常见值live挂单中、filled完全成交、canceled已撤销。accFillSz是累计成交张数avgPx是成交均价。每次重启程序时应该先查一遍未完成订单把live的单子要么撤掉要么接住再开始新的策略循环。否则重启后本地状态归零交易所还有一张挂着行情一波动就会产生意料之外的开仓。3.4 WebSocket 私有频道订阅订单和持仓推送REST 适合“问一次答一次”但成交回报用轮询会很笨。私有 WebSocket 频道能实时推送订单变化和持仓变化下面是登录加订阅的完整写法。import json import time import hmac import hashlib import base64 import websocket def ws_login(api_key: str, secret_key: str, passphrase: str): timestamp str(int(time.time() * 1000)) message timestamp GET /users/self/verify mac hmac.new(secret_key.encode(), message.encode(), hashlib.sha256) sign base64.b64encode(mac.digest()).decode() return { op: login, args: [{ apiKey: api_key, passphrase: passphrase, timestamp: timestamp, sign: sign, }], } def on_message(ws, message): data json.loads(message) if data.get(event) login: ws.send(json.dumps({ op: subscribe, args: [ {channel: orders}, {channel: positions}, ], })) if data.get(arg, {}).get(channel) orders: for o in data.get(data, []): print(o.get(instId), o.get(side), o.get(fillPx), o.get(fillSz)) ws websocket.WebSocketApp( wss://ws.okx.com:8443/ws/v5/private, on_messageon_message, ) ws.run_forever()WebSocket 的登录签名和 REST 不一样它固定用法是timestamp GET /users/self/verify不需要 query 和 body。登录成功后订阅orders和positions两个私有频道前者告诉你每一笔成交明细后者告诉你当前持仓数量。orders推送的fillPx和fillSz才是真实成交价和成交量不是挂单价格。如果回测里按 K 线 close 计算滑点实盘里应该用这个fillPx跟 close 对比慢慢修正你对滑点的假设。这里有个现实问题WebSocket 连接不会永远活着。网络切换、机房升级都可能断开所以框架里必须在on_close里记录断线时间在on_open里启动心跳线程每隔 20 秒发一次ping。没有心跳的连接看起来是通的实际上交易所那边已经把它回收了。4. 把均线策略接到框架里信号生成、仓位与回测的四个参数这一章用最常见的双均线策略做例子。四个核心参数是fast_ma、slow_ma、stop_loss_pct、leverage。前两个决定什么时候开仓后两个决定每次开多少、亏多少离场。理解这四个参数怎么传导比你跑出一个漂亮回测更重要。4.1 策略基类与信号生成策略层不直接碰交易所它只需要接收一个 DataFrame返回一个信号字典。这是整套框架里最关键的设计因为回测和实盘共用同一套信号逻辑。import pandas as pd class Strategy: def on_bar(self, df: pd.DataFrame, account: dict): raise NotImplementedError class MaCross(Strategy): def __init__(self, fast_ma5, slow_ma20, stop_loss_pct0.05): self.fast_ma fast_ma self.slow_ma slow_ma self.stop_loss_pct stop_loss_pct def calc_size(self, account: dict) - int: mark_price account[mark_price] max_notional account[max_notional_usd] if mark_price 0: return 1 return max(1, int(max_notional / (mark_price * 0.01))) def on_bar(self, df, account): df df.copy() df[fast] df[close].rolling(self.fast_ma).mean() df[slow] df[close].rolling(self.slow_ma).mean() prev, curr df.iloc[-2], df.iloc[-1] if prev[fast] prev[slow] and curr[fast] curr[slow]: return {action: buy, sz: self.calc_size(account)} if prev[fast] prev[slow] and curr[fast] curr[slow]: return {action: sell, sz: self.calc_size(account)} return Noneon_bar返回的字典里action是 buy/sellsz是张数。主循环拿到这个字典后再去调 exchange 层下单不要在on_bar里写requests.post。注意我加了df.copy()这是防止指标列污染外部 DataFrame否则第二次调用时df已经带了fast/slow列iloc对不上原始行号信号会逐渐偏移。另一个细节是只用iloc[-2]和iloc[-1]做比较这才是“当前 K 线收盘确认、下一根 K 线执行”的行为。如果直接用iloc[-1]和实时 tick 价格比较就变成了未来函数回测和实盘彻底脱节。4.2 仓位计算与止损USDT 本位合约 size 怎么换策略返回sz的数值不是随意定的。BTC-USDT-SWAP 永续合约一张对应 0.01 BTC名义价值等于标记价格 × 0.01 × 张数。假设你只想单笔最多投 300 USDT计算公式如下。CT_VAL 0.01 # BTC-USDT-SWAP 一张合约对应 0.01 BTC def calc_size_by_notional(max_notional_usd: float, mark_price: float) - int: raw max_notional_usd / (mark_price * CT_VAL) return max(1, int(raw)) # 张数必须为整数至少 1 张 def should_stop(entry_price: float, cur_price: float, pct: float, side: str) - bool: if side buy: return cur_price entry_price * (1 - pct) return cur_price entry_price * (1 pct)很多新手会在这里犯一个错直接用 USDT 数量当sz传进去结果下单接口报无效数量。OKX 合约的张数必须是整数且不同合约的最小张数不同BTC-USDT-SWAP 最小 1 张。你配置里的max_notional_usd: 300在 BTC 价格 65000 时一张合约价值 650 美元实际只能开 1 张实际保证金占用是 650 / 杠杆这和“300 上限”并不完全一致。要理解这是一个“向上取整”约束不是精确资金管理。止损不能用普通平仓单。逐仓多单的止损应该是side: sell reduceOnly: true的市价单reduceOnly保证只减仓不会开反向仓。触发条件建议放在策略循环里检查should_stop(entry, cur, pct, side)而不要依赖交易所的强平价格强平价格是按保证金率算出来的离你心理止损位通常远得多。4.3 回测别直接信手续费、滑点、资金费率三个隐藏成本回测为什么总是比实盘漂亮因为多数回测少算了三样东西。下面是普通用户对应的一些典型成本成本项普通用户水平影响方式手续费maker 0.020%taker 0.050%每次开仓和平仓都要扣滑点0.02% ~ 0.10%市价单按对手价成交限价单可能不成交资金费率每 8 小时结算一次±0.01%~0.05%持仓过夜会被多次收取我见过最离谱的回测是用 K 线的 close 同时作为信号触发价和成交价手续费按 0 算一年线性回测收益 120%实盘一个月亏掉 15%。问题不在策略在回测的成交价太理想。保守做法是买入成交价用next_open × 1.0005卖出成交价用next_open × 0.9995把手续费和滑点合并成一个固定比例扣掉。资金费率没法完全预测但可以按过去 30 天平均费率折算到每次持仓时长里。如果你的策略扣完这三项后年化低于 30%实盘大概率只是给交易所打工。4.4 参数调节先固定风险参数再调均线周期参数怎么调我的血泪经验是不要一股脑把四个参数丢给网格搜索。先把leverage和stop_loss_pct定死比如 3 倍杠杆、5% 止损然后只调fast_ma和slow_ma的周期组合。为什么这两个参数决定信号频率而信号频率直接决定手续费成本。均线周期越短交易次数越多手续费累计越重最后你会看到回测收益随着参数变短先升后崩那是手续费吃掉的。调参时做一张简单的热力图横轴 fast 周期、纵轴 slow 周期、每个格子填扣除成本后的收益选一个“平台区”的中心参数而不是最大值旁边那个孤岛。孤岛参数通常是对历史行情过拟合换一段数据就失效。5. 避坑指南OKX API 的几个典型翻车现场这一章全是真金白银踩出来的经验。下面按“现象、原因、解决”的顺序写遇到问题直接对应查。5.1 报错 50111时间戳和签名总对不上现象下单接口返回code: 50111提示Invalid OK-ACCESS-TIMESTAMP有时候白天正常晚上就频繁失败。原因本地系统时钟不准确或者代码里生成 header 时间戳和签名时间戳用了两个不同的变量。OKX 要求OK-ACCESS-TIMESTAMP用毫秒时间戳服务器对时间偏移容忍度很窄偏差超过几秒就会拒绝。解决先校准系统时间确认 NTP 同步正常然后统一用同一个时间戳字符串参与签名和 header像 3.1 里写的timestamp str(int(time.time() * 1000))这样只生成一次。如果还报错打印本地时间和交易所服务器时间对比别手动改系统时间凑数。5.2 WebSocket 半小时自动断开心跳和代理问题现象程序前 20 分钟收数据正常之后没有报错但订单成交不再推送重启之后又好了。原因没有发送心跳 ping交易所或者网络设备把空闲连接回收了。另一种情况是本地开了系统代理WebSocket 握手走了代理代理空闲超时后主动断开长连接。解决连接建立后启动一个线程每隔 20 秒ws.send(ping)收到pong表示连接正常。如果网络环境必须走代理给 WebSocketApp 显式传入http_proxy_host和http_proxy_port不要依赖系统设置。断线之后要做自动重连并在重连成功后重新登录、重新订阅所有私有频道。5.3 仓位总是对不上tdMode 和 leverage 设置顺序反了现象程序显示买入了 2 张但账户里的保证金占用量比预期大很多或者下单直接返回 51000。原因在逐仓模式下设置杠杆必须在开仓之前完成而且需要指定instId和mgnMode。如果先下单再调杠杆交易所会按默认杠杆计算保证金逐仓的保证金占用自然和本地算的不一样。解决启动时先调用/api/v5/account/set-leverage参数带上instIdBTC-USDT-SWAP, lever3, mgnModeisolated确认返回code:0后再进入策略主循环。如果框架里没有这一步自己补到 health_check 里不要偷懒。5.4 回测收益 80% 实盘亏钱K 线索引偏移和未来函数现象回测曲线非常漂亮参数一到实盘就失效甚至连续止损。原因典型有两个。一个是使用“当前这根 K 线的收盘价”来开下一根 K 线的单导致回测偷看了未来另一个是滚动均线窗口在实盘里还没收集够就提前发出信号相当于用 20 日均线的时候前 5 根 K 线就已经开始交易了。解决回测时只允许用第i根 K 线之前的数据产生信号并且在下一条 bar 开盘成交实盘启动时先等slow_ma 1根 K 线缓冲不要一启动就交易。判断框架有没有未来函数最简单的方法是看第一笔订单的成交时间根策略里的slow_ma参数对比如果出现少于slow_ma根 K 线就开仓的情况肯定有问题。5.5 策略实例互相串信号全局变量没清干净现象同时跑 BTC 和 ETH 两个策略日志里 BTC 策略却执行了 ETH 的止损。原因框架把下单结果写进了类属性或全局字典不同策略实例共享了同一个变量止损函数没有把instId一并传入最后读到哪个策略的持仓取决于遍历顺序。解决所有仓位、止损状态全部挂在以instId为 key 的实例字典里不要用模块级全局变量。下单回调返回时必须带上instId、clOrdId和strategy_name日志里这三者齐全才允许更新状态。代码审查时先 grep 一遍global把共享状态全部清掉再加新策略。6. 上线前的最后一步对账、告警与灰度验证6.1 用三步验证代替“听天由命”框架能跑通和能赚钱是两件事我上线任何策略都强制走三步缺一不可。第一步是模拟盘对账。把 env 设成 demo跑至少 24 小时期间把本地记录的每次下单回执与交易所“持仓/成交”页面逐笔核对。重点看clOrdId是否一一对应成交价与 WebSocket 推送的fillPx是否一致。常见问题是本地记了单但交易所没收到原因是请求超时但服务器实际成交了。所以下单接口超时的时候不能直接判定失败要立刻查订单状态。第二步是断线恢复。手动把网线拔掉 30 秒再插回来观察程序是否能重连 WebSocket、把断线期间的订单拉回来。框架如果只在on_message里更新状态断线期间发生的成交就会丢正确做法是重连成功后主动调用一次/api/v5/trade/orders-pending和/api/v5/account/positions做全量对账把缺失的成交补回来。第三步是小仓位灰度。实盘第一次跑不要直接上配置里的 300 USDT先用 1 张合约跑 50 笔以上核对磨损成本与回测时折算的费率是否一致同时把日志级别调到 INFO记录每次信号的 K 线时间、下单参数、成交回执。日志字段至少包含strategy_name、clOrdId、side、sz、fillPx、state六项缺任何一项都别上线。代码里最终要留一个“所有订单均带 clOrdId 且全局唯一”的断言防止重复下单。从那以后我每次上线新策略都强制走一遍这三步宁可慢一天也不让一台只会在行情好的时候赚钱的机器在震荡市里裸奔。希望帮到你。本文还有配套的精品资源点击获取
阅读完成 · 觉得有帮助？
