Orders

Placing orders

Send an order with POST /v1/order/submit, or with our batch API, POST /v1/order/submit-batch-omni. PAX supports one form of order, a limit order, with a TIF of GTC or IOC. Internally, cancels are treated similarly to orders: a cancel removes liquidity from your oldest orders at a given price level first; see Canceling orders.

Field	Description
market_id	Integer id of market; see Markets.
side	ASK, BID. See Enums.
ticks	Limit price in ticks; see PAX units.
qty	Quantity, scaled from base asset native units [1].
tif	IOC, GTC. See Enums.

See Data Formats for unit conversions.

Note 1. Quantity must be a multiple of qty_step_size, at most max_qty, and worth at least min_notional; see PAX units.

Canceling orders

PAX cancels orders by their limit price, in FIFO order, up to the quantity you specify. PAX supports cancel by order id, but cancel by id is translated into cancel by limit price internally; see Cancel by order id.

Cancels & queue priority

Liquidity is added to the back of a price level’s queue and removed from the front, whether by a fill or by a cancel.

Event	How	FIFO treatment
LIQ_ADD	By new resting limit order.	Added to the back of the price level.
LIQ_RMD	By a trade: EX or XA.	Removed from the front of the price level (price-time).
LIQ_RMD	By cancel: CX.	Removed from the front of the price level [2].

Note 2. A cancel removes liquidity from your oldest resting order at that price first, and if your cancel requests more quantity than that order has, the cancel continues to remove liquidity from your next oldest order at that price until either you have no more liquidity at that price or the amount of quantity specified in your cancel request has been canceled. You can view this as a price-time matching algorithm running on your orders at the specified price only.

Cancel by order id

The compatibility API supports cancel by order_id. PAX will look up your order, and if it has not yet been filled, issue a cancel by price for that order’s remaining quantity. Internally, cancel by id becomes cancel by price.

Cancel by id may cancel different orders.

Example

Suppose you have two bids at 100,000 ticks. Order A for 300, placed first, and order B for 500 [3]. You send a cancel for order B (using the cancel by id API). PAX turns this into a cancel of 500 (B’s remaining quantity) at 100,000 ticks. In this case, because A is still resting, it is canceled first and the remaining 200 quantity to cancel are applied to order B.

Order id	Before	Removed	After	Status
A	300	300	0	CANCELED
B	500	200	300	RESTING

Note 3. Here, A and B stand in for real order ids, which are UUIDs, e.g. 0192f6c0-7d3e-7a41-9c2b-5e8f1a6d3b20.

Order status updates

Fills and confirms are sent by order status update (OSU) messages. OSUs report each acceptance, fill, cancel, and rejection.

You can subscribe to the real-time OSU stream over the WebSocket. Using the REST API, you can query up to 10,000 of your most recent fills in real time, or with up to a 15 minute time delay query for an order’s full OSU history.

Order status update message

Field	Description
osu_id	Exchange-assigned id of this update. Empty for a refused order.
order_id	Exchange-assigned order id. Empty for a refused order.
client_order_id	Optional user-supplied id (string, up to 36 bytes).
qty_filled_make	Filled as maker in this update.
qty_filled_take	Filled as taker in this update.
qty_canceled	Canceled in this update.
fill_value	Notional filled, in quote native units.
fee_rebate	Fee (negative) or rebate (positive), in quote native units.
order	The original order.
order_status	Order status. See Enums.
reason	Order status reason. See Enums.

Quantities reported

An OSU is sent for each change to an order, and its quantity fields cover only that change. For example, your GTC bid for 1,000 has a limit price that crosses the spread. It takes the 300 qty at the best ask and rests its remaining 700 qty [4]. Later, one seller takes 400 qty and another takes 300 qty:

Update	qty_filled_take	qty_filled_make	order_status
1	300	0	RESTING
2	0	400	RESTING
3	0	300	FILLED

Note 4. In the public market data feed, the initial taker fill is reported with event type LIQ_RMD and qualifier XA (execute and add); see Book Building.

Cancels

The outcome of a cancel is reported by OSU, whether it removes all, part, or none of the requested quantity. A cancel’s own OSU reports the amount it removed in qty_filled_take and any amount it couldn’t remove in qty_canceled. Each of your orders it reduces also gets an OSU, with the reduced amount in qty_canceled.

For example, you have two bids at 100,000 ticks: order A for 300 qty, placed first, and order B for 500 qty. You cancel 400 qty at 100,000 ticks:

OSU for	qty_filled_take	qty_canceled	order_status
The cancel	400	0	FILLED
Order A	0	300	CANCELED
Order B	0	100	RESTING

If you had instead canceled 1,000 qty, the cancel would have removed the full 800 qty you had resting, with its own OSU reporting qty_filled_take 800, qty_canceled 200, and status PARTIAL. Your orders A and B would have received OSUs reporting qty_canceled 300 and 500, respectively, each with status CANCELED.

An order’s lifecycle

              ┌──► RESTING ──┬──► FILLED
              │   (GTC only) ├──► PARTIAL
PENDING ──────┤              └──► CANCELED
              ├──► FILLED
              ├──► PARTIAL
              ├──► CANCELED
              └──► REJECTED

#	Status	Meaning
1	PENDING	Accepted, awaiting the matching engine.
2	RESTING	On the book, possibly partly filled. GTC only.
3	FILLED	Fully filled.
4	CANCELED	Canceled with nothing filled.
5	PARTIAL	Partly filled, rest canceled.
6	REJECTED	Refused, e.g. insufficient balance.