Skip to content
First Access Exchange

Orders

Orders are dYdX's: MsgPlaceOrder carries an Order, MsgCancelOrder an order id. The chain-market rules on top are a price cap, a price band on calls and the company perpetual, no TWAP orders, and the isolation rules (chain markets).

The order id

An order is identified by its OrderId:

FieldMeaning
subaccount_id{owner, number}: the address and subaccount the order belongs to
client_idAny uint32 you choose; unique among your open orders with the same flags and book
order_flags0 short-term, 64 long-term, 32 conditional, 128 TWAP (refused on chain markets)
clob_pair_idThe book, from /dydxprotocol/clob/clob_pair (perpetual_clob_metadata.perpetual_id names the market)

Short-term and long-term

Short-term (order_flags 0)Long-term (order_flags 64)
Expirygood_til_block: a block height, at most 40 blocks ahead (ShortBlockWindow)good_til_block_time: unix seconds, at most 95 days ahead (StatefulOrderTimeWindow), checked against the previous block's time
Where it livesIn each validator's memory; only its fills reach chain stateIn chain state
When it matchesAs soon as a validator receives itFrom the block after the one that includes it
Sequence numberNot used: replay-protected by good_til_blockUsed, one order a transaction
Gas feeNoneNone
Time in forceAnyNot IOC
Counts for S, the call marks and the indexNoYes
Shown byThe indexer's order book onlyThe chain's stores and the indexer

Market makers who want their quotes to move the implied market caps and the company index must quote with long-term orders. The trading app sends short-term orders good for 20 blocks.

Time in force

time_in_forceBehaviour
TIME_IN_FORCE_UNSPECIFIED (0)Matches what it can, then rests the rest on the book: a limit order
TIME_IN_FORCE_IOC (1)Matches what it can; the rest is cancelled, never rests. Short-term only
TIME_IN_FORCE_POST_ONLY (2)Rests only as a maker: an order that would cross the book is cancelled
TIME_IN_FORCE_FILL_OR_KILL (3)Deprecated and refused

Order types

dYdX's clients and indexer name order types; on chain they are combinations of the fields above.

TypeOn chain
LimitTIME_IN_FORCE_UNSPECIFIED, short-term or long-term
Post-only limitTIME_IN_FORCE_POST_ONLY
MarketA short-term IOC order at a worst acceptable price
Stop limit, stop market, take profitConditional orders, order_flags 32 (stop orders)
TWAPorder_flags 128: refused on chain markets

Market orders. There is no unpriced market order: a market buy is an IOC buy at the highest price you accept. On the company perpetual the useful worst price is the top of the price band (a higher one is refused); on a call it is the top of its band; on a binary up to $0.999. What doesn't fill at once is cancelled.

Reduce-only

reduce_only makes an order only reduce the subaccount's position. An order that would flip the position is resized to what remains of it. Reduce-only requires IOC: the chain refuses a reduce-only order that isn't immediate-or-cancel ("reduce only orders must be short term IOC orders"). A conditional order with IOC can be reduce-only.

Prices and sizes

  • quantums: whole contracts, above 0.
  • subticks: micro-dollars a contract, a multiple of the book's tick, above 0: 10,000 ($0.01) on a perpetual, call or put; 1,000 ($0.001) on a binary (units).
  • On a binary, from 0.1¢ to 99.9¢ (1000 to 999000); an order outside that range, $1 included, is refused.
  • At most the market's price cap: K on a put, governance's cap on a call or a company perpetual.
  • On a company perpetual, within the band around the index: I ± 10% while the index is fresh, ± 2% otherwise (company perpetuals).
  • On a call, within its mark ± 50%, at least ± 5 ticks (options).

Collateral

  • A long-term order on a chain market must be covered, with the subaccount's other resting long-term orders on that side, as if they all filled; and the subaccount may rest long-term orders on only one chain-market book at a time.
  • Every match is checked against the subaccount's margin; an order whose subaccount can't pay for a match is removed (ORDER_REMOVAL_REASON_UNDERCOLLATERALIZED).
  • Equity tiers limit how many open orders a subaccount may have (limits).

Open interest caps

On a call and on the company perpetual, a match that would take open interest above the cap is refused for the taker. The resting maker stays; the taker goes on to makers that close positions, passing over those that would open. A taker that passed over a maker doesn't rest: what it couldn't fill is cancelled.

Cancels

MsgCancelOrder names the order id and its own expiry:

  • a short-term cancel carries a good_til_block at least the order's (and at most 40 blocks ahead); it is free and skips the sequence number;
  • a long-term or conditional cancel carries a good_til_block_time at least the order's.

MsgBatchCancel cancels up to 100 short-term orders of one subaccount at once.

A long-term order can't be replaced in place: cancel it and place a new one with another client id.

Removals

An order can leave the book without a cancel. The chain's reasons (OrderRemoval.RemovalReason) and the indexer's (ORDER_REMOVAL_REASON_*) include:

ReasonWhen
UNDERCOLLATERALIZEDIts subaccount couldn't pay for a match
POST_ONLY_WOULD_CROSS_MAKER_ORDERA post-only order would have crossed
IMMEDIATE_OR_CANCEL_WOULD_REST_ON_BOOKWhat an IOC order didn't fill
SELF_TRADE_ERRORIt would have matched its own subaccount's order
REDUCE_ONLY_RESIZEA reduce-only order resized away
VIOLATES_ISOLATED_SUBACCOUNT_CONSTRAINTSIt would open a second market in an isolated subaccount
FINAL_SETTLEMENTIts market halted (untriggered and triggered stop orders too)
EXPIREDIts good-til passed
OUTSIDE_CALL_PRICE_BANDFirst Access: a long-term order or a triggered stop on a call's or the company perpetual's book that meets a maker only outside the band

A market's halt cancels every resting order on its book.

Placing them

The API guide places and cancels orders with dYdX's TypeScript and Python clients and the CLI, with complete, tested examples.