price between 0.01 and 0.99. Use the default time_in_force (gtc) to rest on the book, or ioc to fill immediately and cancel the remainder.
Endpoint
Authentication
This endpoint requires HMAC authentication. Include the
Key, Timestamp, and HMAC headers on every request. See the authentication guide for signing instructions.Headers
Optional. A unique value chosen by the client for a logical operation. Replaying the same
POST with the same key and the same body after a successful response returns the stored response without creating a duplicate order. A replay while the first request is still running returns 409. A different body (for example, a new price) produces a different fingerprint, so requoting is not blocked.Request
Send decimals as strings ("0.42"). It keeps the HMAC signature simple and avoids float rounding.
Number of shares to buy or sell. Must be greater than
0.02. For OOM and USDC on the preview host, use at most two decimals: the signed intent counts shares in units of 0.01.On an ask, the string "max" sells the shares you hold minus the shares reserved by your open asks. The resolved quantity is returned in shares_requested. "max" requires a price, is rejected on a bid (InvalidSharesMax), and returns NoSellableShares when there is nothing to sell. For OOM and USDC on the preview host, send an explicit share count: the signed sharesRaw must equal the quantity "max" resolves to, which you cannot know for certain when you sign. A mismatch fails the signature check.A create without shares is rejected with InvalidShares.Optional cap, only valid with
shares: "max". The order sells the smaller of this value and the sellable amount.Limit price as a probability, from
0.01 to 0.99, in steps of 0.01. A price with more than two decimals is rejected.null or omitted makes a market order. Market orders are rejected for OOM and USDC on the preview host with price_required: send a price with time_in_force: "ioc".Position direction. Use
long to bet in favor of the outcome, or short to bet against it.gtc (default): the order rests on the book until it is fully filled or canceled. ioc (immediate or cancel): the order fills right away at price or better, and any unfilled remainder is canceled. ioc requires a price and does not match your own resting orders.ISO 8601 datetime after which the order no longer matches.
null for none. For a signed order the API lowers it to the signed expiry if it is later or missing.When
true, your open asks that reserve the shares this ask needs are canceled before the new order is placed. Without it, that case returns OrderBookConflictingOrders.Optional. Your expected total, used only as a cross-check. It does not size the order. Leave it out unless you want the create to fail when the book moved.
Signed intent fields (phase one)
Required forOOM and USDC on the preview host. Take the values from POST /orders/signing-context/ and the signature you made over its eip712 payload.
The
nonce you signed. Send it. When omitted, the API assumes the Safe’s current nonce. A nonce another order already used returns order_intent_nonce_stale; a nonce above the current one returns order_intent_nonce_not_issued.The
maxUsdcRaw you signed, in raw token units (6 decimals). Send it. It follows the live book, so this is how the API verifies the amount you actually signed. A value below what the order needs now returns max_usdc_raw_too_low. It is 0 for asks.market, side, position, price, shares, the nonce, the expiry, and maxUsdcRaw. The order you send must match what you signed in every one of them, or the signature does not verify.
Response
Returns201 Created with the order object. A gtc order is returned as processing: matching runs after the response. An ioc order is matched before the response but can still read processing while its fills settle. Read the final state from List orders.
The event the market belongs to:
id, title, slug, status, is_wagerable, resolve_date, bet_end_date, order_book_enabled, resolution_mode, markets_count.The market (outcome), as a nested object:
id, title, title_verbose, price, long_label, short_label, status, resolution, and volume, liquidity, and depth figures. It is not a bare ID.Shares still unfilled.
Shares the order was created with.
Shares filled so far.
For a finished
ioc order, the shares that were canceled. 0 otherwise, including while an ioc order is still processing.Net cash of the fills where this order was the taker, after the fee: what a bid paid or an ask received.
null if it has no taker fill.processing, open, filled, partial_filled, partial_filled_cancelled, or canceled. See Order lifecycle.On-chain state:
ready, approval_pending, settling, settled, failed, none, or empty. See Settlement.amount field in the response, and the timestamp is created, not created_at.
Error codes
Errors use the format in Errors, which lists every code with its HTTP status and what to do. The ones you are most likely to meet:On-chain codes arrive in a
400 as the detail of the entry whose attr is "code". See On-chain order errors look different.Example
A signedioc bid on the preview host. The body uses string values, so the HMAC string is built from exactly these strings.
Sample response (201 Created), nested objects trimmed