> ## Documentation Index
> Fetch the complete documentation index at: https://docs.qfex.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 私密订单 API

> 使用一个 dark 布尔值控制私密挂单，以及仅撮合私密流动性的即时执行。

私密订单使用现有的已认证 [Trade WebSocket](https://docs.qfex.com/cn/websocket/channels/trade/authenticate.md) 和 `add_order` 请求，无需使用单独的接口。

> [!NOTE]
>
> 私密订单提交必须由交易所启用。未启用时，`dark: true` 请求会返回 `err.error_code: "InvalidOrder"`，原因为 `InvalidOrderType`。

## 请求字段

| 字段 | 类型 | 默认值 |
| - | - | - |
| `dark` | JSON boolean | 省略时为 `false` |

请使用 JSON `true` 或 `false`，不要使用字符串、数字或 `null`。该字段的含义取决于订单能否挂入订单簿。

## 支持的组合

| 订单类型 | 有效期 | `dark: true` 的行为 |
| - | - | - |
| `LIMIT` | `GTC` | 入场撮合可以成交公开或私密流动性；剩余数量以私密方式挂单。 |
| `ALO` | `GTC` | 以私密方式挂单；若会吃掉符合条件的流动性，则取消订单。 |
| `LIMIT` | `IOC` | 仅成交限价范围内的私密被动挂单；剩余数量取消。 |
| `LIMIT` | `FOK` | 仅成交限价范围内的私密被动挂单；必须全额成交，否则取消且不产生任何成交。 |
| `MARKET` | `IOC` | 仅成交通常价格区间内的私密被动挂单；剩余数量取消。 |
| `MARKET` | `FOK` | 仅成交通常价格区间内的私密被动挂单；必须全额成交，否则取消且不产生任何成交。 |

当 `dark: false` 或省略该字段时，即时订单可以成交公开和私密流动性，GTC 的剩余数量则公开挂单。ALO 对两类流动性都保持仅挂单属性。独立触发单和 TWAP 请求不支持私密指令。附带的触发单遵循现有生命周期，不会继承父订单的私密指令。

## 私密限价挂单

此订单在入场时可以成交公开或私密流动性，剩余数量以私密方式挂单。如果不允许任何主动吃单，请改用 `ALO GTC`。

```json theme={null}
{
  "type": "add_order",
  "params": {
    "symbol": "AAPL-USD",
    "side": "BUY",
    "order_type": "LIMIT",
    "order_time_in_force": "GTC",
    "quantity": 10,
    "price": 100.05,
    "dark": true,
    "reduce_only": false,
    "client_order_id": "private-gtc-001"
  }
}
```

示例中的数量和价格必须符合交易品种的价格增量、数量增量及风险限额。`reduce_only` 是独立的布尔字段，其含义不变。

## 仅撮合私密流动性的吃单订单

对于 `LIMIT IOC`、`LIMIT FOK` 和 `MARKET IOC/FOK`，`dark: true` 会使公开对手方订单不符合撮合条件。撮合按符合条件的私密订单中的最优价格执行，同价则按时间优先。系统不会与公开 BBO 比较，也不要求存在公开报价，不会回退至公开流动性。

```json theme={null}
{
  "type": "add_order",
  "params": {
    "symbol": "AAPL-USD",
    "side": "BUY",
    "order_type": "LIMIT",
    "order_time_in_force": "IOC",
    "quantity": 10,
    "price": 100.20,
    "dark": true,
    "client_order_id": "private-ioc-001"
  }
}
```

假设公开卖价为 USD 100.10，符合条件的私密挂单仅在 USD 100.15 有三份合约，此订单会以 USD 100.15 买入三份，并取消剩余七份。公开卖单不受影响。同一请求若使用 `FOK`，由于没有十份符合条件的私密合约，会取消且不产生任何成交。价格为 USD 100.10 的私密卖单符合条件，高于限价的私密卖单则不符合条件。

市价单必须提供数值 `price: 0`；该值不是执行限价。价格区间和常规风险检查仍然适用。如果需要明确限定最高买入价或最低卖出价，请使用限价单。

```json theme={null}
{
  "type": "add_order",
  "params": {
    "symbol": "AAPL-USD",
    "side": "BUY",
    "order_type": "MARKET",
    "order_time_in_force": "IOC",
    "quantity": 1,
    "price": 0,
    "dark": true,
    "client_order_id": "private-market-001"
  }
}
```

## 成交发布取决于被动方订单

| 被动方订单 | 公开逐笔成交 |
| - | - |
| 公开订单 | 发布，与主动方的 `dark` 值无关。 |
| 私密订单 | 不发布，与主动方的 `dark` 值无关。 |

MDS 在实时发布和重连重放中应用此规则；HTTP API 在公开成交历史中应用此规则。私密 GTC 可以先吃掉公开流动性，产生公开的入场成交，再将剩余数量私密挂单，之后产生不公开的被动成交。普通吃单订单与私密被动挂单成交时，也不会产生公开逐笔成交。仅撮合私密流动性的即时订单与私密被动挂单成交，因此不会产生公开逐笔成交。

## 响应与核对

`order_response`、`get_order_response` 及 `all_orders_response.orders` 中的每条订单记录，都会通过可选字段 `dark: true` 表示私密指令。默认值 `false` 会被省略；解码时应将字段缺失视为 `false`。已废弃的双字段元数据不会返回。

以下片段省略了其他标准订单响应字段：

```json theme={null}
{
  "order_response": {
    "order_id": "5b309929-206f-40ec-804d-cbe46e81afc1",
    "client_order_id": "private-gtc-001",
    "symbol": "AAPL-USD",
    "status": "ACK",
    "type": "LIMIT",
    "time_in_force": "GTC",
    "dark": true,
    "quantity": 10,
    "quantity_remaining": 10,
    "price": 100.05,
    "side": "BUY",
    "reduce_only": false
  }
}
```

请订阅[订单响应](https://docs.qfex.com/cn/websocket/channels/trade/order.md)及[成交回报](https://docs.qfex.com/cn/websocket/channels/trade/fills.md)。`FILLED` 事件可能仅表示部分成交；应处理每次成交和最终撤单。IOC 的剩余数量使用正常的 `CANCELLED` 响应。FOK 不会提交部分成交。

重连后，[获取用户订单](https://docs.qfex.com/cn/websocket/channels/trade/get_user_orders.md)及[获取单笔订单](https://docs.qfex.com/cn/websocket/channels/trade/get_order.md)会向账户所有者返回仍有效的私密订单。已完成的即时订单不属于有效挂单；请使用已认证的[成交历史](https://docs.qfex.com/cn/websocket/channels/trade/get_user_trades.md)查询执行结果。成交回报及成交历史负载沿用现有结构，不新增 `dark`；如有需要，可通过 `order_id` 与订单状态关联。

## 修改、撤单与错误

[修改订单](https://docs.qfex.com/cn/websocket/channels/trade/modify_order.md)会保留 `dark`。该字段不能通过改单写入；如需更改，请取消并提交新订单。请发送当前必填的 `reduce_only` 值，并使用客户端改单后返回的新订单 ID。普通撤单、恢复及断线撤单规则同样适用于私密挂单。

格式错误或非布尔值的 `dark` 会产生 `InvalidJSONFormat`；未知的新增订单字段会被忽略。在订单提交时被拒绝的不支持的订单类型或有效期组合会返回 `err.error_code: "InvalidOrder"`，并在错误消息中注明 `InvalidOrderType` 或 `InvalidTimeInForce`。现有的数量、限价、价格区间、风险及速率限制检查保持不变。

## 从早期草案迁移

请从新增订单请求中移除 `visibility` 和 `liquidity_pool`，改用 `dark`。这些已废弃字段会被忽略；未提供 `dark: true` 时，旧请求会按普通方式公开挂单，或不受私密流动性限制地吃单。它们也不能通过改单写入。不包含任何私密指令的现有请求继续按正常方式处理。

## 市场数据与经济计算

公开 BBO、深度、聚合深度及 `market_stats` 的 BBO 部分，仅包含公开挂单数量。撮合引擎在应用公开深度限制前，从公开深度快照中排除私密数量；MDS 和 HTTP 深度接口使用这些仅含公开数量的快照，重连缓存也使用相同快照。

私密订单及所有成交仍保留在内部订单簿和账目中，并正常参与资金费率、标记价格、持仓、风险、结算、K 线及成交量计算。公开逐笔成交按上述被动方可见性规则发布，对手方成交回报及已认证历史记录不受影响。因此，公开汇总值不一定等于公开逐笔成交之和，衍生数据也可能透露私密交易活动。请参阅[交易规则](https://docs.qfex.com/cn/qfex/order-types.md#private-only-taking-orders)。


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.