Orders

The Order API carries signed economic intent. Request authentication proves which API credential sent a command; the EIP-712 order signature independently proves what the authorized signer agreed to trade. An acknowledgement is not a fill, and a fill is not settlement.

Endpoint summary

Every write requires canonical request authentication and Idempotency-Key. Create/amend additionally require the signed typed data described in Authentication.

Economic intent

• BUY increases exposure to the explicit outcome_id at prices no worse than limit_price.
• SELL reduces exposure, or opens/increases short exposure only when Market and account rules permit, at prices no worse than limit_price.
• Clients MUST name market_id and outcome_id; they MUST NOT infer YES/NO from a quote position.
• Draft v0.1 has no unbounded market-order primitive. Immediate execution uses a protected marketable limit order with FOK or FAK and an explicit worst acceptable price.

Time in force and maker behavior

IOC is accepted in explanatory/client UX language as the industry alias for FAK; the canonical wire value MUST be FAK.

post_only=true is valid only for GTC or GTD. If any part would execute immediately, the complete order is rejected with ORDER_POST_ONLY_WOULD_TAKE; it receives no fill. Maker/taker is ultimately recorded per Fill, not guaranteed merely by a limit price.

Create an order

{
  "client_order_id": "client_demo_20260831_001",
  "account_id": "acct_demo_001",
  "market_id": "mkt_demo_001",
  "outcome_id": "out_demo_yes_001",
  "side": "BUY",
  "order_type": "limit",
  "limit_price": "0.6400",
  "quantity": "150.00",
  "time_in_force": "GTC",
  "expires_at": null,
  "post_only": true,
  "reduce_only": false,
  "cancel_on_pause": true,
  "self_trade_prevention": "cancel_taker",
  "maximum_fee": "1.00",
  "maximum_notional": "96.00",
  "settlement_asset_id": "asset_demo_collateral_001",
  "signature_type": "eoa",
  "signature_version": "1",
  "order_nonce": "order_nonce_demo_4401",
  "order_signature": "0xILLUSTRATIVE_SIGNATURE_ONLY"
}

All economic fields MUST be covered by the EIP-712 T17Order message. The signed representation uses integer + scale pairs (for example limit_price_integer=6400, limit_price_scale=4) rather than relying on JSON string parsing. It includes:

• account/funder, signer, Market, Outcome, and side;
• limit price integer/scale and quantity integer/scale;
• time in force, expiry, post-only, reduce-only, and cancel-on-pause;
• self-trade prevention mode;
• hash of client_order_id;
• order nonce and typed-data signature version;
• maximum fee/risk/notional cap and settlement asset;
• environment/audience through domain separation.

The transport body MAY add non-authorizing labels, but any field capable of changing price, size, side, execution, fee, funding, expiry, or risk effect MUST be signed. The server compares signed and transport values byte-for-byte after canonical normalization.

{
  "data": {
    "order_id": "ord_demo_001",
    "client_order_id": "client_demo_20260831_001",
    "command_id": "cmd_demo_001",
    "status": "open",
    "received_at": "2026-08-31T12:00:00.100Z",
    "validated_at": "2026-08-31T12:00:00.120Z",
    "acknowledged_at": "2026-08-31T12:00:00.130Z",
    "original_quantity": "150.00",
    "filled_quantity": "0.00",
    "remaining_quantity": "150.00",
    "average_fill_price": null,
    "reserved_amount": "96.00",
    "engine_sequence": 992001,
    "rejection": null
  },
  "meta": {
    "request_id": "req_demo_order_001",
    "published_at": "2026-08-31T12:00:00.130Z",
    "schema_version": "1.0"
  }
}

This response only reports state known at acknowledgement. A fast marketable order may already be filled, partially_filled, or canceled; authoritative executions are still separate Fill records.

Validation order

The server evaluates commands in this deterministic order:

1. Parse JSON, media type, and protocol/schema version.
2. Authenticate API key, environment, and required scopes.
3. Enforce request timestamp, nonce, replay, and idempotency.
4. Verify EIP-712 domain, signature type, signer/account authorization, order nonce, expiry, and signed/body equality.
5. Resolve Market and Outcome; enforce trading entitlement and Market state.
6. Validate side, price/quantity precision, tick/lot/minimum, time-in-force compatibility, and expiry.
7. Enforce balance/collateral, reservations, position limits, reduce-only, fee/notional caps, and price protection.
8. Enforce self-trade prevention and post-only behavior.
9. Acknowledge accepted/rejected state and publish sequenced private events.

The first failing stage determines the primary rejection code. field_violations MAY report independent schema failures from the same stage, but the server MUST NOT leak sensitive downstream account/risk details after an earlier auth failure.

Order state machine

received
  ├── rejected
  └── validated
       ├── open ── partially_filled ── filled
       │    ├── cancel_pending ── canceled
       │    ├── expired
       │    └── suspended ── open/canceled
       ├── filled                       immediate full execution
       ├── partially_filled ── canceled FAK remainder
       └── canceled                     unfilled FAK/FOK

Draft states are received, validated, rejected, open, partially_filled, filled, cancel_pending, canceled, expired, suspended, and failed. failed is reserved for an internal order-processing failure after validation and MUST include an auditable reason; settlement failure does not rewrite an order as failed.

An order response includes timestamps for every reached transition, original/filled/remaining quantity, average fill price, fee accrued, reserved amount, version, engine sequence, and terminal reason. A client MUST use version or engine_sequence to ignore stale projections.

Deterministic immediate-order outcomes

• FOK succeeds: the full quantity produces one or more Fills; final order state is filled.
• FOK cannot fully execute: zero Fills; final state is canceled with terminal_reason=FOK_NOT_FILLED.
• FAK has liquidity: available quantity fills; remaining quantity is canceled; projection records both quantities.
• FAK has no liquidity: zero Fills; final state is canceled with terminal_reason=FAK_NO_FILL.
• Post-only crosses: whole order is rejected; zero Fills.
• GTD expires: unmatched remainder becomes expired no later than the signed expiry under the engine’s authoritative clock.

Self-trade prevention

Supported modes are:

The account default is explicit and returned by account policy; clients MUST NOT guess it. Fills sequenced before STP triggers remain valid and are not rolled back.

Reduce-only, pause, and price protection

• reduce_only=true permits only execution that reduces the named Outcome position under the account’s position model. A quantity that would cross through zero is either capped or rejected according to a returned account policy; it MUST NOT silently open the opposite exposure.
• cancel_on_pause=true requests cancellation of resting remainder when the Market enters paused. The transition is asynchronous and remains subject to a race with earlier engine-sequenced Fills.
• Every immediately marketable order has an explicit worst limit_price. maximum_notional and maximum_fee are signed additional caps. Server risk controls may be stricter.

Batch placement

POST /orders/batch contains an ordered orders array. Each item carries its own client_order_id, order nonce, and signature; the request has one Idempotency-Key. Results map to the zero-based input index and independently report accepted or rejected.

{
  "data": [
    { "index": 0, "status": "accepted", "order_id": "ord_demo_001" },
    {
      "index": 1,
      "status": "rejected",
      "error": {
        "code": "ORDER_TICK_SIZE_INVALID",
        "message": "limit_price is not aligned to price_increment.",
        "retryable": false
      }
    }
  ],
  "meta": {
    "request_id": "req_demo_batch_001",
    "published_at": "2026-08-31T12:00:00Z",
    "schema_version": "1.0"
  }
}

Draft v0.1 does not promise all-or-none batch atomicity. Request-level authentication/schema failure rejects the request; otherwise each item is independently validated and reported.

List and detail

GET /orders supports market_id, outcome_id, status, side, client_order_id, created_after, created_before, updated_after, cursor, and limit. Default order is (created_at, order_id) descending. GET /orders/{order_id} returns the complete projection and links to Fill IDs and settlement records; it does not embed private signature bytes by default.

Amend/replace

POST /orders/{order_id}/amend is an atomic cancel/replace instruction against expected_order_version. The request specifies the desired new economic intent and carries a fresh order nonce and EIP-712 signature. The server either:

• accepts the replacement, cancels the old remaining quantity, and returns replaced_by_order_id; or
• rejects the amend and leaves the old order unchanged.

Quantity already filled cannot be amended. If a race advances the order version before the command reaches its engine cutoff, the server returns ORDER_VERSION_CONFLICT with the latest safe projection. Draft v0.1 does not define in-place priority preservation; a replacement receives new priority.

Cancel one order

{
  "expected_order_version": 3,
  "client_cancel_id": "cancel_demo_001",
  "reason": "user_request"
}

An accepted cancellation enters cancel_pending until the engine cutoff is known, then canceled for remaining quantity. Fills with a lower/equal authoritative cutoff sequence may arrive before or after the HTTP acknowledgement and remain valid. Repeating the same idempotent cancel returns the original result.

Cancel-all / kill switch

POST /orders/cancel-all requires at least one explicit scope filter: account_id plus optional market_id, index_id, venue_id, or cancel_on_pause_only. scope=all_open_orders is an explicit high-impact choice, never a default.

The result reports command_id, number targeted, cancellation states, per-order failures, and an engine cutoff/resume cursor. New order blocking is a separate account-risk control; cancel-all alone MUST NOT be described as disabling future placement.

Representative rejection matrix

See Errors for the common envelope and retry rules, and WebSocket for authoritative private order updates.