add_order request. There is no separate endpoint.
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
Use JSON
true or false, not strings, numbers or null. The meaning depends on whether the order can rest.
Supported combinations
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. UseALO GTC instead when no aggressive execution is permitted.
reduce_only is a separate boolean with its normal meaning.
Private-only taking orders
ForLIMIT 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.
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.
Trade publication follows the passive order
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:
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 and get order return active private orders to their owner after reconnecting. Completed immediate orders are not active orders; use authenticated trade history 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 preservesdark. 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
Removevisibility 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 ofmarket_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.