实验性组合 API

组合（Combo） 将固定比例的多条期权腿作为一个订单进行交易。每次成交都会同时执行所有必需的腿。您的持仓仍然是各个单独的期权。

实验性合约

所有 /experimental 端点以及明确标注为实验性的 WebSocket 消息均不稳定。 破坏性变更可能在提前一天（24 小时）通知后生效，包括删除或重命名字段或端点、更改字段类型，以及更改请求或响应行为。变更将在 API 变更日志中公布。客户端必须关注这些通知，并在规定的生效时间之前完成更新。现有的非实验性 API 合约不受此政策约束。

可用性取决于您所在的环境。本页描述的是实验性接口，并不代表其已在生产环境上线，也不代表交易应用中推出了新的界面。

有关通用的连接与签名约定，请参阅 REST 参考、认证指南和 WebSocket 指南。

发现组合

请求	结果
`GET /experimental/combos`	一页有上限的未到期定义，可按 `underlying` 筛选
`GET /experimental/combos/{symbol}`	单个未到期定义及其解析后的期权腿

首单创建： 当组合尚无法被发现时，通过 POST /order 提交规范化的 combo_definition。第一笔被接受的订单会发布其定义，包括立即成交的订单。被拒绝的订单不会发布任何内容。不存在单独的创建端点。

可发现期限： 定义在其第一条腿到期之前始终可被发现，即使没有挂单也是如此。

分页： 响应包含 combos 和 next_cursor。将 limit 设为 1–1,000（默认 100）。在下一次请求中将返回的游标作为 cursor 传入，并保持相同的 underlying 筛选条件。游标为 null 表示未观察到更多记录。无效的 limit 或游标将返回 HTTP 400。

GET /experimental/combos?underlying=BTC&limit=100
GET /experimental/combos?underlying=BTC&limit=100&cursor=<next_cursor>

分页排序： 先按最早的腿到期日排序，再按组合 ID 排序。请将游标视为不透明值。每一页反映的是当前的发现状态；在两次请求之间，定义可能到期或新增。请使用创建更新或重新开始发现，以获取排在已保存游标之前的新建定义。

标识： 符号由 COMBO- 加上 64 个小写十六进制字符组成。其内容绑定的 ID 固定了各腿的合约及带符号的整数比例。已存在的符号不能改变含义。

初始范围： 两至八条不同的期权腿，且标的资产相同。每条腿都必须已上市、未到期，并且符合所请求执行路由的条件。

理解方向、价格与数量

对于比例为 +1 A, -1 B 的规范定义：

买入一个组合： 买入一份 A，卖出一份 B。
卖出一个组合： 卖出一份 A，买入一份 B。
净价： price(A) - price(B)，按每个组合报价。
限价： 买单接受不高于其限价的净价；卖单接受不低于其限价的净价。

负价格和零价格均有效。 如果 A 以 $8 成交、B 以$ 10 成交，则规范净价为 -2。买入该组合在扣除费用前收到 $2。卖出该组合在扣除费用前支付$ 2。每条实际期权腿的执行价格仍为正值。

订单最小变动单位： 组合数量使用人类可读的合约单位，最小变动单位为 0.000001；净限价的最小变动单位为 0.000001。每条已执行的腿还必须满足其自身的数量和价格最小变动单位。部分成交会保持所有比例不变，并成交完整的、允许的组合数量。

费用： 沿用现有的逐腿费率和资格规则，组合不享受折扣。传入订单在其自身的腿上为吃单方（taker），并使用其提交的 builder 归属。在"单腿经由组合"的路由中，组合父订单在与辅助单腿挂单方成交的额外辅助腿上获得常规的吃单方费用归属；这些腿没有 builder 归属。挂单中的组合预留会保守地按各腿总金额计入预期的吃单费用。当前标准保证金（Standard Margin）的执行要求订单簿和 RFQ 成交的交易费用为零；涉及 SM 参与者的路由在交易费用非零时无法执行。

保证金： 交易所会针对每个账户检查由此产生的期权持仓和剩余订单敞口。组合不会跨钱包合并抵押品，也不承诺任何特定的保证金减免。如果您的账户等级只允许卖出备兑期权，则单腿挂单与每个组合父订单的卖出腿共享同一份已成交的多头库存。不同的父订单和拆分成交不能各自重复使用该库存；未成交的买入腿不会增加覆盖额度。

下单

使用现有的签名 POST /order 请求，并填入组合符号。订单签名字段保持不变。 请对您发送的 symbol、size 和 price 字符串原样签名，包括负价格的负号。对于新组合，请按下文所述添加其规范的 combo_definition。签名中内容绑定的符号承诺了该定义；不匹配的定义将被拒绝。已知组合可以省略该字段。

{
  "wallet": "<your wallet>",
  "symbol": "<discovered COMBO symbol>",
  "side": "Buy",
  "size": "1",
  "price": "-2",
  "tif": "gtc",
  "route": "best_execution",
  "client_id": "spread-001",
  "reduce_only": false,
  "mmp_enabled": false,
  "nonce": 1,
  "signature": "<signed order>"
}

请将占位符和 nonce 替换为您的实际值。此价格仅为示例，并非当前市场报价。

设置	行为
`route: "book_only"`	匹配可用的直接流动性和受支持的隐含流动性，然后应用有效期规则
`route: "best_execution"`	考虑进行整组合价格改善拍卖，并在适当时回退至订单簿执行
`route: "rfq_only"`	在 `/order` 上会被拒绝
`tif: "gtc"`	未成交的组合剩余部分挂单
`tif: "ioc"`	撤销未成交的剩余部分
`tif: "fok"`	全部成交所请求的组合数量，否则完全不成交

价格改善 将整个组合的带符号净价与可执行的全量订单簿参考价进行比较。报价方必须按所请求的精确比例和数量提供每一条腿。仅按第一条腿对报价排序是不够的。直接组合流动性和受支持的隐含路由都可以为参考价做出贡献。参考价不可用或不完整时，订单将转入订单簿执行。

报价资格： 现有的 RFQ 费用规则同样适用。如果任一参与者使用标准保证金，RFQ 执行要求交易费用为零。未通过费用、抵押品或精确分配检查的报价，会使执行继续沿用当前的订单簿路径；它不会部分执行其各条腿。

隐含撮合 可以将一个组合与其辅助的单腿期权流动性结合。例如，A 的单腿订单可以与 A 减 B 的组合以及 B 的流动性原子性成交。仅交易 A 的客户不会获得 B 的持仓。

隐含搜索有资源上限。如果单腿订单达到这些上限、其辅助流动性变得不可用，或者可选路由无法表示该单腿订单的最小变动单位，它仍然可以按常规订单规则与其直接期权订单簿成交。组合支持不会改变单腿订单可接受的数量或价格最小变动单位。目标期权必须仍符合订单簿交易条件。超出搜索上限的组合订单将被拒绝，且不会进行部分分配。

当前限制： 原生组合订单要求 mmp_enabled: false。受保护的单腿参与者保留 MMP。触发阈值的组合会完成其各条腿并停止后续撮合；未完成的 FOK 或原子替换会回滚整个候选成交。只减仓订单会跳过价格改善拍卖并使用订单簿准入，其中每条由此产生的腿都必须通过只减仓检查。可使用现有的撤单端点，通过父订单 ID 或客户端订单 ID 撤销挂单中的组合。

替换： PUT /order 可以在同一组合定义内原子性地替换父订单。被拒绝的替换会保持原订单不变。批量替换中的原生条目同样对每个父订单使用一条原子命令；整个批次并不是一个全有或全无的事务。在组合与单腿之间，或在不同组合定义之间进行替换，将被拒绝。

自成交防护： 在某条路由将使账户与自身成交之前，撮合会停止，并撤销挂单方订单。此前已完成的成交保留，传入订单的剩余部分被撤销。如果此前没有成交，传入订单将被拒绝。FOK 订单和失败的原子替换保持其全有或全无的行为，包括回滚暂定的挂单方撤单。

在首单中定义组合

签名前进行规范化： 合并重复的合约 ID，移除比例为零的腿，按数值对 ID 排序，将比例除以其最大公约数，并使第一个比例为正。如果规范化反转了比例，请反转预期的订单方向并对净价取反。如果规范化将比例除以某个因子，请将组合数量乘以该因子，并将净价除以该因子。

版本一的 ID 为以下拼接内容的 Keccak-256：

UTF-8("hypercall:combo-definition\0")
|| version as unsigned 16-bit big-endian (1)
|| leg count as unsigned 16-bit big-endian
|| each sorted leg:
     instrument ID as 32 big-endian bytes
     ratio as signed 64-bit two's-complement big-endian

合约 ID 为 UTF-8 "instrument" 后接精确的规范期权符号的 Keccak-256。发布的组合 ID 为完整摘要，编码为 0x 加 64 个小写十六进制字符。组合符号在 COMBO- 之后使用相同的十六进制字符。

在普通的签名 POST /order 请求体中包含 combo_definition。该定义包含 version、id 和 legs；每条腿包含 instrument_id 和 ratio。ID 编码为 0x 加 64 个小写十六进制字符，比例编码为规范的带符号十进制字符串，例如 "1" 或 "-1"。比例使用 JSON 数字、前导加号或前导零将被拒绝。

{
  "combo_definition": {
    "version": 1,
    "id": "<canonical content hash as 0x plus 64 hex digits>",
    "legs": [
      {"instrument_id": "<first canonical instrument ID>", "ratio": "1"},
      {"instrument_id": "<second canonical instrument ID>", "ratio": "-1"}
    ]
  }
}

此片段需添加到上文完整的订单示例中。请将占位符替换为实际 ID，并使用对应的 COMBO- 符号。不需要额外的定义签名，也没有单独的发布 nonce。服务会根据签名符号验证规范内容及其标识；单腿订单必须省略 combo_definition。

接受与发现： 每笔被接受的组合订单都会在其持久化订单记录中保留其定义，并以幂等方式确保目录条目存在。后续订单不会覆盖首次创建记录。立即成交的订单仍会生成发现数据；被拒绝的订单则不会。由于发现数据是从已提交数据投影而来，它可能滞后于订单确认。支持在后续订单中重新提交相同的定义，包括在其首个目录条目仍在追赶时。

读取订单与执行

请求	用途
`GET /experimental/orders`	读取带有明确合约分类的订单，包括组合父订单
`GET /experimental/trades`	默认读取真实的腿成交，或通过 `view=packages&symbol=<COMBO symbol>` 读取单个组合的组合摘要
`GET /experimental/fills`	默认读取钱包成交，或通过 `view=packages` 读取钱包的组合摘要

有关支持的筛选条件和游标，请参阅 REST 参考。组合视图使用 limit（1 至 1,000，默认 100）和 before_execution_id 分页，而非 offset：传入返回的 next_before_execution_id 以获取下一页。组合成交要求提供规范的 COMBO- symbol；组合成交明细接受 wallet 和可选的 symbol。组合摘要是分组记录： 执行 ID 和腿成交 ID 可让您将其与实际期权执行关联。计算账户合计时，请勿将组合数量、权利金或费用再叠加到组成执行上。

标识符精度： 实验性订单 ID、组合执行 ID、组成成交/订单 ID、父订单 ID 以及组合分页游标均为十进制字符串。请在客户端中将其保留为字符串；将其转换为 JavaScript 数字可能会丢失精度。旧版 view=legs 响应保留其现有表示形式。

兼容性： 旧版合约发现和订单视图保留其单腿约定。实际的期权腿执行继续出现在旧版成交/成交明细推送中，持仓仍为期权持仓。组合的父订单并不是一组独立挂单的腿订单。

显式订阅

实验性私有频道需要现有的 WebSocket 认证步骤和显式订阅。它们只发布已认证钱包的父订单记录。

频道	消息	受众
`experimental_order_updates`	`ExperimentalOrderUpdate`，包含父订单 ID、符号、合约类型（`option`、`perp` 或 `combo`）、状态、数量、已成交数量和净价	已认证钱包
`experimental_combo_trades`	`ComboTrade`，包含执行 ID、符号、组合数量、净价和腿成交 ID	公开
`experimental_combo_fills`	`ComboFill`，包含该钱包的父订单 ID、方向和组合执行	已认证钱包

{"type":"Subscribe","channel":"experimental_order_updates"}

ExperimentalOrderUpdate.status 使用 Acked、Open、PartiallyFilled、Filled、Canceled 或 Rejected，而不是 OrderUpdate 的大写值。ID 和数量均为字符串。

使用已发现的组合符号订阅现有的订单簿频道：

{"type":"Subscribe","channel":"orderbook","symbols":["<discovered COMBO symbol>"]}

市场发现更新 可能会重复推送同一个不可变定义；请按组合 ID 去重。它们在 market_updates 上使用 MarketUpdate，带有 action: "ComboCreated"、组合符号、ID、规范腿和时间戳。在客户端对账时，请将发现、父订单状态、组合执行摘要和实际腿成交视为不同的记录。

发现组合​

理解方向、价格与数量​

下单​

在首单中定义组合​

读取订单与执行​

显式订阅​

发现组合

理解方向、价格与数量

下单

在首单中定义组合

读取订单与执行

显式订阅