8.1 六家加密交易所适配器

8.1 六家加密交易所适配器

本节摘要：QuantDinger 内置六家加密交易所的实盘适配器（官方 README 口径）：Binance、OKX、Bitget、Bybit、Gate、HTX。本节先讲统一适配层的职责边界——它把行情、下单、账户查询抽象成统一接口，把各家差异吸收在适配器内部，但精度档位、最小下单量、费率档位这类"参数级差异"仍要逐所核对；然后是本节的重头戏：API key 权限最小化的完整清单——只开交易权限、禁用提币、绑定 IP 白名单、一用途一 key、定期轮换；接着给出测试网先行的验证清单与从测试网切到主网的门槛；最后用一份配置示例把接入动作固化。原则只有一条：权限上宁可少开再补，不可多开再收。

学习目标

• 说清统一适配层抽象了什么、不抽象什么。
• 逐项执行 API key 权限最小化清单。
• 按测试网清单完成先行验证，明确切主网的门槛。
• 用配置文件固化单所接入，避免手工操作漂移。

一、统一适配层：抽象了什么，不抽象什么

六家交易所的 REST 与 WebSocket 接口、字段命名、错误码体系各不相同。适配层（官方 README 口径支持上述六家）在上层策略与各家接口之间做翻译：

统一适配层的位置

 策略(Strategy API V2) ──▶ trading-worker ──▶ 统一订单接口
                                              │
        ┌──────────┬──────────┬──────────┬────┴─────┬──────────┐
        ▼          ▼          ▼          ▼          ▼          ▼
     Binance     OKX       Bitget     Bybit      Gate       HTX
      适配器      适配器      适配器      适配器      适配器      适配器
   （各家接口、错误码、限频规则被吸收在适配器内部）
​

它抹平的：接口协议、字段口径、订单状态机、基础限频处理。它抹不平的（策略层与配置层自己负责）：

接入每一家时，先用第 07 章的可执行性检查把这张表过一遍——精度与最小量这类约束，适配器会校验并拒绝，但"能通过校验"和"适合你的资金规模"是两回事。

参数级核对也可以脚本化。下单前在 sizing 侧先按交易所公布的精度档位自行取齐一遍（示意逻辑，精度档位以各所官方文档为准）：

# check_order_params.py —— 下单参数按精度档位取齐与下限校验（示意，档位以交易所官方为准）
from decimal import Decimal, ROUND_DOWN

def align_order(price, qty, spec):
    """spec 形如 {"tick": "0.01", "step": "0.001", "min_qty": "0.001", "min_notional": "5"}"""
    tick, step = Decimal(spec["tick"]), Decimal(spec["step"])
    px = Decimal(str(price)).quantize(tick, rounding=ROUND_DOWN)  # 价格按 tick 向下取齐
    qx = Decimal(str(qty)).quantize(step, rounding=ROUND_DOWN)    # 数量按 step 向下取齐
    problems = []
    if qx < Decimal(spec["min_qty"]):
        problems.append("低于最小下单量")
    if px * qx < Decimal(spec["min_notional"]):
        problems.append("低于最小成交额")
    return {"price": str(px), "qty": str(qx), "ok": not problems, "problems": problems}
​

两个讲法。其一，取齐方向选向下：向上取齐可能越过档位边界被拒，向下取齐最坏只是少买一点点。其二，这段代码不是替代适配器的校验，而是把参数级差异从"运行时报错"提前到"策略设计期发现"——如果回测的 sizing 天天产出 0.00347 这样的数量，问题应该在回测配置里就暴露，而不是等实盘适配器拒单三次、告警两条之后才发现。用 Decimal 而不是浮点，是因为精度取齐本身就是二进制浮点最不擅长的运算。

二、API key 权限最小化：一份不可妥协的清单

API key 泄露是自托管交易系统的第一大真实风险。最小化原则：key 的权限集合，恰好覆盖系统需要做的事，一项不多。逐项执行：

第 6 项展开一句：QuantDinger 的密钥管理方式以官方文档为准，但"密钥最终落在哪个文件、这个文件是否被备份与同步到了别处"是你的责任，接入前应当亲自确认一遍存放路径与权限。

这六条与《Harness 工程：从零打造智能体运行环境》第 05 章《权限与审批门》里"给智能体的凭证永远只给最小集"是同一条纪律在交易场景的落地：你不会把保险柜钥匙连同密码一起交给信使，也不该给出金权限随交易 key。

三、测试网先行：验证清单

六家交易所普遍提供测试网（testnet）环境，名称与申请方式以各家官方文档为准。切主网前，在测试网完成：

第 5 项容易被跳过，但它最重要：错误的形态（错误码、字段、重试是否安全）决定了实盘第一次撞上它时系统是优雅降级还是连环重试。第 7 项把"出事时来不来得及"提前变成肌肉记忆。

四、配置示例与切换门槛

（示意结构，字段名与适配器名称以官方文档为准。）

# exchange_binance.yaml —— 交易所接入配置（示意，字段以官方文档为准）
exchange:
  name: binance
  environment: testnet          # testnet | mainnet，切换必须走审批
  credentials_env: QD_BINANCE_KEY   # 密钥从环境变量读，不落明文
symbols: [BTC/USDT]
trading:
  order_types: [market, limit]
  rate_limit_margin: 0.8        # 限频余量，只用八成（示意值）
safety:
  max_daily_orders: 50          # 单日订单数上限（示意值，按策略定）
  kill_switch: enabled          # 应急开关绑定（第 10 章）
reconcile:
  schedule: daily               # 每日对账（第 8.3 节）
​

从测试网切主网的门槛（全部满足才切换）：

• 测试网七项清单全绿，且连续运行一段时间无异常（量级建议：一至两周，示意建议）。
• 主网初始资金刻意取小：先让系统管理"亏了不心疼"的规模（具体金额自行决定，原则是先验证运维再谈规模）。
• 切换动作本身走变更流程：改 environment 字段、双人复核、记录时间点，切换日盯盘观察首个完整交易日。

五、常见问题与排查

排查表背后是本节的两条主线：凡涉及"单被拒"，先分清是参数级差异（第一、五行，配置问题）还是账户与权限问题（五行），前者改配置，后者走权限清单复查；凡涉及"钱对不上"，一律先降级运行再排查（第四行），对账纪律在第 8.3 节展开。测试网与主网行为不一致（第一行）是最消磨信心的一类问题——它的存在正是"测试网先行、清单全绿才切换"这条门槛的理由，而不是绕过它的借口。

本节要点回顾

• 适配层抹平接口差异，抹不平精度、最小量、费率档位——参数级核对不可省。
• key 权限最小化六条清单：只交易、禁提币、IP 白名单、一用途一 key、轮换、环境变量存放。
• 测试网七项清单里，错误处理与应急开关演练最不能省。
• 切主网有门槛：清单全绿、资金刻意取小、切换走变更流程。

加密所是七乘二十四小时的世界，传统券商不是。下一节看 IBKR 与 Alpaca 两条券商通道：市场时钟、T+1 结算、保证金制度三个结构性差异，会如何改写你的 scheduler 配置与风控规则。