> ## 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.

# Private-order API

> One dark boolean for private resting orders and private-only immediate execution.

Private orders use the existing authenticated [Trade WebSocket](https://docs.qfex.com/websocket/channels/trade/authenticate.md) and `add_order` request. There is no separate endpoint.

> [!NOTE]
>
> Private-order entry must be enabled by the exchange. When it is disabled, `dark: true` requests return `err.error_code: "InvalidOrder"` with an `InvalidOrderType` reason.

## Request field

| Field | Type | Default |
| - | - | - |
| `dark` | JSON boolean | `false` when omitted |

Use JSON `true` or `false`, not strings, numbers or `null`. The meaning depends on whether the order can rest.

## Supported combinations

| Order type | Time in force | `dark: true` behavior |
| - | - | - |
| `LIMIT` | `GTC` | Entry matching may take displayed or private liquidity. Any remainder rests privately. |
| `ALO` | `GTC` | Rests privately; cancels instead of taking eligible liquidity. |
| `LIMIT` | `IOC` | Takes only private passive liquidity within the limit; cancels the remainder. |
| `LIMIT` | `FOK` | Takes only private passive liquidity within the limit; fills completely or cancels without fills. |
| `MARKET` | `IOC` | Takes only private passive liquidity within normal price bands; cancels the remainder. |
| `MARKET` | `FOK` | Takes only private passive liquidity within normal price bands; fills completely or cancels without fills. |

With `dark: false` or omitted, immediate orders may take both displayed and private liquidity, and GTC remainders rest displayed. ALO remains post-only against both visibility classes. Private instructions are not supported on standalone stops or TWAP requests. Attached stops follow their existing lifecycle and do not inherit the parent's private instruction.

## Resting private limit

This order may execute against displayed or private liquidity on entry; any remainder rests privately. Use `ALO GTC` instead when no aggressive execution is permitted.

```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"
  }
}
```

Illustrative quantities and prices must satisfy the symbol's tick, lot and risk limits. `reduce_only` is a separate boolean with its normal meaning.

## Private-only taking orders

For `LIMIT IOC`, `LIMIT FOK`, and `MARKET IOC/FOK`, `dark: true` makes displayed counterparties ineligible. Matching selects the best eligible private prices, with time priority at the same price. There is no displayed-BBO comparison, displayed-quote requirement or fallback to displayed liquidity.

```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"
  }
}
```

With a displayed ask at USD 100.10 and only three eligible private contracts at USD 100.15, this buys three at USD 100.15 and cancels seven. The displayed ask remains untouched. The same request with `FOK` cancels without any fills because ten eligible private contracts are unavailable. A private ask at USD 100.10 is eligible; one above the limit is not.

Market orders require numeric `price: 0`; this is not an execution limit. Price bands and normal risk checks still apply. Use a limit order for an explicit maximum buy price or minimum sell price.

```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"
  }
}
```

## Trade publication follows the passive order

| Passive order | Public individual trade print |
| - | - |
| Displayed | Published, regardless of the aggressor's `dark` value. |
| Private | Not published, regardless of the aggressor's `dark` value. |

MDS applies this rule to live publication and reconnect replay; the HTTP API applies it to public trade history. A private GTC can first take displayed liquidity, producing public entry fills, and then rest privately, producing private passive fills later. A regular taker matching a private passive order also produces no public print. Private-only immediate orders match private passives and therefore produce no public prints.

## Responses and reconciliation

`order_response`, `get_order_response` and each entry in `all_orders_response.orders` expose optional `dark: true` for private instructions. The default `false` is omitted; decode absence as `false`. The retired two-field metadata is not returned.

This excerpt omits other standard order-response fields:

```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
  }
}
```

Subscribe to [order responses](https://docs.qfex.com/websocket/channels/trade/order.md) and [fills](https://docs.qfex.com/websocket/channels/trade/fills.md). A `FILLED` event can describe a partial fill; process every fill and final cancellation. IOC remainders use the normal `CANCELLED` response. FOK does not partially commit fills.

[Get user orders](https://docs.qfex.com/websocket/channels/trade/get_user_orders.md) and [get order](https://docs.qfex.com/websocket/channels/trade/get_order.md) return active private orders to their owner after reconnecting. Completed immediate orders are not active orders; use authenticated [trade history](https://docs.qfex.com/websocket/channels/trade/get_user_trades.md) for executions. Fill and trade-history payloads retain their existing schemas and do not add `dark`; correlate `order_id` with order state when needed.

## Amendments, cancellations and errors

[Modify order](https://docs.qfex.com/websocket/channels/trade/modify_order.md) preserves `dark`. It is not a writable modify field; cancel and submit a new order to change it. Send the required current `reduce_only` value and use the replacement order ID returned by a client modification. Ordinary cancellation, recovery and cancel-on-disconnect behavior also applies to private resting orders.

Malformed/non-boolean `dark` produces `InvalidJSONFormat`; unknown add-order fields are ignored. Unsupported type/time-in-force combinations rejected at order entry return `err.error_code: "InvalidOrder"` with an `InvalidOrderType` or `InvalidTimeInForce` reason. Existing size, limit, price-band, risk and rate-limit checks are unchanged.

## Migration from the earlier draft

Remove `visibility` and `liquidity_pool` from add-order requests and use `dark` instead. Those retired fields are ignored; without `dark: true`, an old request uses ordinary displayed-resting or unrestricted-taking behavior. They are not writable modify fields either. Existing requests that omit all private instructions continue to behave normally.

## Market data and economic calculations

Public BBO, depth, aggregated depth and the BBO portion of `market_stats` contain displayed resting quantities only. The engine excludes private quantities from public depth snapshots before public depth limits; MDS and HTTP depth use these displayed-only snapshots, including for reconnect caching.

Private orders and all executions remain in the internal book and accounting. Funding, marks, positions, risk, settlement, candles and volumes include them normally. Individual public prints follow passive visibility as described above, while counterparty fills and authenticated history are unaffected. Public aggregate totals therefore need not equal the sum of public prints, and derived data can reveal private activity. See the [trading rules](https://docs.qfex.com/qfex/order-types.md#private-only-taking-orders).


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