Skip to main content
An order is an instruction to buy or sell shares in a market outcome. When you place an order, you specify which market you want to trade, which side (buy or sell), what position to take, how many shares, and at what price. Orders are created via POST /orders/, listed via GET /orders/, and canceled via PATCH /orders/{id}/cancel/. You can also cancel several orders or cancel everything in a single call. There is no endpoint that returns a single order by ID, and no fills or trades endpoint: filter GET /orders/ and read the fill fields on the order.
On the phase-one preview host, orders in OOM and USDC settle on-chain. Each create must carry an EIP-712 LimitOrderIntent signed by your Safe owner key, in addition to HMAC. Matching stays off-chain. See On-chain trading and Environment.

Order types

Set price and leave time_in_force at its default gtc (good till canceled). The order fills against anything that crosses it, and the remainder rests on the book until it fills or you cancel it.
The examples show order fields only. On the preview host you add the signed-intent fields described in Create order.

Side: bid vs ask

The side field specifies whether you are buying or selling shares.

Position: long vs short

The position field specifies which direction you are betting.
Long and short positions can both be bought (bid) or sold (ask). For example, selling a long position (ask + long) reduces your existing long exposure.

Price and size rules

Matching

Orders match by price, then time. The best crossing price fills first, whether it belongs to another user or to the platform AMM. At the same price, a resting user order fills before the AMM, and among user orders the oldest fills first. A bid long and a bid short on the same market whose prices sum to 1 or more also match each other, without an ask on the book. See On-chain trading. The taker (the order that arrives second) pays the fee. See Fees.

Order lifecycle

Every order starts in processing. What happens next depends on time_in_force. How each type moves:
  • gtc — create returns processing. Matching runs after the response. The order then becomes open or filled. Partial fills keep it open. It ends as filled or canceled.
  • ioc — matching runs inside the create request. The order ends as filled, partial_filled_cancelled, or canceled (nothing filled). The create response can still show processing while its fills settle; read the final state from GET /orders/. If matching cannot finish in the request, the order is canceled and create returns 503 IOCUnavailable.
An order leaves the book as canceled when you cancel it, when its event closes, or when the platform cancels a bid your Safe balance no longer covers.

What you can cancel

Canceling stops the unmatched remainder. A fill whose on-chain transfer has already been sent stands.

Expiration

expired_at is the time after which the order no longer matches. On the preview host it is never later than the expiry you signed: the API lowers expired_at to the signed expiry. An expired order stops matching, but the API does not change its status at that moment, so cancel it if you need it to read canceled.

Settlement

On the preview host, matching and settlement are separate steps. The engine matches off-chain, then moves collateral on-chain asynchronously. Shares are credited only after the collateral transfer succeeds; until then the order can show processing. If the transfer fails, the match fails and no shares change hands. settlement_mode is onchain for these orders. settlement_status tracks the chain side: To follow fills without polling, subscribe to order-update on your private channel.

The order object

Create and list return the same object. There is no amount field on the order.

Order fields reference

shares is the size of the order and is required. amount is an optional cross-check for the total; it does not size the order, and you can leave it out.On an ask, shares can be the string "max" to sell everything you hold that is not reserved by your open asks, optionally capped with max_shares. "max" cannot be relied on for OOM or USDC on the preview host: the signed sharesRaw must equal the resolved quantity, so send an explicit share count.
Set expired_at to an ISO 8601 datetime to stop the order from matching after that time. See Expiration.
An ask fails with OrderBookConflictingOrders when your open asks already reserve the shares it needs. Set cancel_conflicting_orders to true to cancel those asks and place the new one.

Full order fields

The signed-intent fields (chain_id, order_intent_signature, order_intent_expiry, order_intent_nonce, max_usdc_raw) are listed in Create order.
Real money orders (USDC, USDT, USD) are restricted in some countries. See Currencies for details.