Skip to main content
Place an order on a specific market outcome. Set 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.
On the phase-one preview host (Environment), every order in OOM or USDC must also carry a signed LimitOrderIntent: send the signed intent fields below. HMAC alone returns 400. Production (https://api.futuur.com) does not accept those fields yet.

Headers

string
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.
integer
required
The market (outcome) ID to place the order on.
string
required
Order side. Use bid to purchase shares or ask to sell shares.
string
required
Currency for the order. One of USDC, USDT, USD, or OOM.
decimal | string
required
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.
decimal
Optional cap, only valid with shares: "max". The order sells the smaller of this value and the sellable amount.
decimal
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".
string
default:"long"
Position direction. Use long to bet in favor of the outcome, or short to bet against it.
string
default:"gtc"
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.
string
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.
boolean
default:"false"
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.
decimal
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 for OOM and USDC on the preview host. Take the values from POST /orders/signing-context/ and the signature you made over its eip712 payload.
string
required
Hex EIP-712 signature of the LimitOrderIntent, made by the Safe owner EOA.
integer
required
The expiry you signed (Unix seconds). Must be in the future.
integer
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.
integer
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.
integer
Optional. Defaults to the active chain (84532 on the preview host).
The intent covers 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.
The nonce is one counter per Safe and each accepted order uses the next value. Run signing context → sign → create one order at a time per Safe. Two orders signed from the same signing context cannot both be accepted. After any failed create, fetch a new signing context before signing again.

Response

Returns 201 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.
integer
required
Unique ID of the created order.
object
required
The event the market belongs to: id, title, slug, status, is_wagerable, resolve_date, bet_end_date, order_book_enabled, resolution_mode, markets_count.
object
required
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.
string
required
Order side: bid or ask.
string
required
Position direction: long or short.
string
required
Currency used: USDC, USDT, USD, or OOM.
number
Limit price.
number
required
Shares still unfilled.
number
required
Shares the order was created with.
number
required
Shares filled so far.
number
required
For a finished ioc order, the shares that were canceled. 0 otherwise, including while an ioc order is still processing.
number
Average fill price, or null before any fill.
number
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.
string
required
gtc or ioc.
string
required
processing, open, filled, partial_filled, partial_filled_cancelled, or canceled. See Order lifecycle.
string
Expiration datetime, or null.
string
required
ISO 8601 datetime when the order was created.
string
required
onchain for signed orders, otherwise ledger or empty.
string
required
On-chain state: ready, approval_pending, settling, settled, failed, none, or empty. See Settlement.
integer
Chain of an on-chain order, or null.
There is no 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 signed ioc 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
For the full flow in runnable Python, see End-to-end Python bot.