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:
| Field | Meaning |
|---|---|
subaccount_id | {owner, number}: the address and subaccount the order belongs to |
client_id | Any uint32 you choose; unique among your open orders with the same flags and book |
order_flags | 0 short-term, 64 long-term, 32 conditional, 128 TWAP (refused on chain markets) |
clob_pair_id | The 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) | |
|---|---|---|
| Expiry | good_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 lives | In each validator's memory; only its fills reach chain state | In chain state |
| When it matches | As soon as a validator receives it | From the block after the one that includes it |
| Sequence number | Not used: replay-protected by good_til_block | Used, one order a transaction |
| Gas fee | None | None |
| Time in force | Any | Not IOC |
| Counts for S, the call marks and the index | No | Yes |
| Shown by | The indexer's order book only | The 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_force | Behaviour |
|---|---|
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.
| Type | On chain |
|---|---|
| Limit | TIME_IN_FORCE_UNSPECIFIED, short-term or long-term |
| Post-only limit | TIME_IN_FORCE_POST_ONLY |
| Market | A short-term IOC order at a worst acceptable price |
| Stop limit, stop market, take profit | Conditional orders, order_flags 32 (stop orders) |
| TWAP | order_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¢ (
1000to999000); 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_blockat 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_timeat 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:
| Reason | When |
|---|---|
UNDERCOLLATERALIZED | Its subaccount couldn't pay for a match |
POST_ONLY_WOULD_CROSS_MAKER_ORDER | A post-only order would have crossed |
IMMEDIATE_OR_CANCEL_WOULD_REST_ON_BOOK | What an IOC order didn't fill |
SELF_TRADE_ERROR | It would have matched its own subaccount's order |
REDUCE_ONLY_RESIZE | A reduce-only order resized away |
VIOLATES_ISOLATED_SUBACCOUNT_CONSTRAINTS | It would open a second market in an isolated subaccount |
FINAL_SETTLEMENT | Its market halted (untriggered and triggered stop orders too) |
EXPIRED | Its good-til passed |
OUTSIDE_CALL_PRICE_BAND | First 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.