GuidesTrading
Order lifecycle
How an order moves from accepted to filled, cancelled, expired or invalidated, and how to follow it live.
After the API accepts an order, the order book tries to match it. Each match is settled on-chain by the exchange contract. An order ends in one of four final statuses.
Statuses
GET /v1/orders and GET /v1/orders/{hash} return each order's status:
| Status | What it means | Final |
|---|---|---|
OPEN | The order was accepted and still has shares to fill. A limit order rests on the book. | No |
FILLED | The order filled completely. A market order is FILLED after any fill, because the rest of it is cancelled. | Yes |
CANCELLED | The order was cancelled. See the causes below. | Yes |
EXPIRED | The order reached its expiration before it filled. | Yes |
INVALIDATED | Predict removed the order because it can't be matched or settled any more, for example after a failed settlement. | Yes |
An order is cancelled when:
- You removed it through the API, or cancelled it on-chain. See Cancel orders.
- A market order found nothing to match within its slippage, or a fill-or-kill order couldn't fill completely.
- A post-only order would have matched right away.
- Self-trade prevention cancelled it.
- A check that runs after the API responds found your balance or allowance too low.
amount is the order's size, and amountFilled is how much of it has been settled, both in wei.
Matched and settled
A match and a settlement are two steps:
- Matched. The order book pairs your order with others. It locks the matched shares, so no other order can take them, and submits a transaction to the exchange contract.
- Settled. The transaction succeeds on-chain. Now the shares and USDT have moved, and
amountFilledgrows.
Between the two steps, the locked amount shows in the order book's settlementsPending. See Prices and order book.
A settlement can fail. What happens next depends on why it failed:
- Often the locked liquidity goes back to the book, and the orders can match again.
- An order that caused the failure, for example because its balance changed, is removed. Its status becomes
INVALIDATED. - A market order whose settlement fails is cancelled.
Follow your orders live
The WebSocket topic predictWalletEvents/{jwt} streams events for every order of the wallet that the JWT belongs to. The server checks the JWT when you subscribe. So after a reconnect, subscribe again with a JWT that hasn't expired. See Authentication for getting one.
| Event | When you get it |
|---|---|
orderAccepted | The order was placed in the book. |
orderNotAccepted | The order was rejected. reason is noMarketMatch, rejectedDuplicate or rejectedPostOnly. |
orderMarketMatchPlan | How a market order will fill: plannedFill, and the remainderCancelled that won't fill. |
orderTransactionSubmitted | The order matched, and its settlement was submitted on-chain. An order that matches your own order gets one as taker and one as maker. |
orderTransactionSuccess | The settlement succeeded. |
orderTransactionFailed | The settlement failed. |
orderCancelled | The order was cancelled or invalidated. reason is selfTradePrevention when self-trade prevention cancelled it. |
orderExpired | The order reached its expiration. |
Every event has the order's orderId and orderHash, a timestamp in epoch milliseconds, and details such as the marketId, the outcome, the price and the quantityFilled. The wallet events reference has every field.
Follow your orders shows how to subscribe in TypeScript and Python, print each event, and recover after a reconnect.