Orders API

The Orders API is the only public HTTP surface for manual order submission and mutation. Every operation requires a user-owned key with trade and an owned, credentialed account.

Operations

Mandatory preflight

1. Re-read GET /v1/meta/agents/me and require trade.
2. Read GET /v1/accounts and select an owned account.
3. Read GET /v1/exchanges/{exchange}/tickers; require an orderable ticker.
4. Read GET /v1/accounts/{account_id}/symbol-capabilities immediately before sizing. Respect price/quantity increments, minimums, leverage, margin, and reduce-only support.
5. Ask the human before a materially destructive bulk cancellation or close.

Do not send market_type; routing is derived from exchange and symbol. Use the exact request union in OpenAPI for the chosen execution kind.

Retry identity and acceptance

Public callers do not send Idempotency-Key on create endpoints; it is an internal API-to-Broker transport detail. The API creates it when a create request first arrives and reuses it if the Broker acknowledgement needs one safe in-request retry. client_order_id is venue order identity, not HTTP retry state. Two separate public create requests remain two intentional orders even when their bodies match.

A successful placement is an accepted order resource, not proof of a fill. Preserve the returned order_id and follow its projection. Venue order IDs can appear later and identify exchange-native children.

The public top-level lifecycle is closed to these values: accepted, watching, triggered, submitting, working, partially_filled, completed, cancelled, expired, and failed. Venue- and graph-specific states remain available on typed legs and relations; they do not leak new ad-hoc values into the top-level status.

Sizing rules

• Decimal quantities and prices are sent as strings where the OpenAPI schema specifies decimal strings.
• Spot/perpetual orders are normally base-quantity sized with qty.
• A Polymarket market BUY is quote-budget sized: provide quote_amount in USDC and omit qty. quote_amount is rejected for sells, non-market execution, and non-Polymarket venues.
• Polymarket limit and market SELL quantities remain share-denominated.
• Never round independently of symbol-capabilities; reject or resize with the human's approval when a requested amount is below a venue minimum.

Native and managed state

GET /v1/orders/open is the venue-live projection. working-orders is the broker-managed execution graph for triggers, algorithms, protection, and other multi-leg behavior. A placement ID is not automatically a working-order ID; use the response's working-order projection and relations.

Use replace/amend for venue-live orders and the working-order mutation paths for managed graphs. Cancelling a managed parent must use its public working order ID; cancelling a native order requires the identifiers required by the cancel request schema.

Conditional capability entries expose trigger_reference with the effective price source and configurable: false. Conditional working-order projections carry the same source on the triggered order (and on each protection child as trigger_price_reference). This is the observation that fires the order; an entry_fill_avg trigger reference on a relative protection level is only the arithmetic anchor used to calculate that level.

Chase orders

Chase uses the existing POST /v1/orders endpoint, not a separate Chase API. Read GET /v1/order-capabilities with the exact account_id, exchange, and symbol and inspect orders.chase.supported and orders.chase.execution_mode. The current supported route is managed Polymarket Perp (polymarketperp), not Polymarket prediction markets. Availability remains capability-owned.

Example request body for a BTC buy (illustrative size, not an instruction to trade; replace the account ID and verify the market's quantity requirements):

{
  "account_id": "your-account-id",
  "exchange": "polymarketperp",
  "symbol": "BTC/PUSD:PUSD",
  "order": {
    "side": "buy",
    "qty": "0.001",
    "execution": {
      "kind": "chase",
      "max_chase_distance": "25"
    }
  }
}

max_chase_distance is optional and must be positive when supplied. In this example it means 25 PUSD of adverse price movement from the first Chase target, not 25%, 25 basis points, or a 25-PUSD order budget. Omit the field for no user-defined distance limit. The Chase execution variant does not accept price, price_limit, or time_in_force; these belong to other execution variants. The managed route derives its price from the same-side best quote and submits post-only children.

Keep the accepted response's public order_id and follow GET /v1/orders/working-orders/{order_id}. Repricing can replace the underlying venue child ID without creating a new user instruction. Filled quantity is cumulative across those children, and only the confirmed remainder is resubmitted.

To stop the Chase parent, send the following body to POST /v1/orders/cancel, using its public working-order ID:

{
  "order_id": "your-chase-working-order-id"
}

Do not substitute the latest child's exchange_order_id to stop the whole Chase workflow. Wait for the parent cancellation result; completed fills and their position remain. Chase is not a static limit-level edit: use the working-order projection's advertised actions, and cancel/recreate the parent when changing the instruction.

The Chase user guide covers bid/ask tracking, distance boundaries, partial fills, and market-data interruptions.

Bulk operations

open/cancel-all and positions/close-all are intentionally scoped by their request body. Resolve and display the exact account, exchange, symbol/token, and position impact before sending. A partial result is represented per item in the typed bulk response; do not report global success when any item failed.

Order-type guidance

The user-oriented orders/order-types topic explains limit, market, trigger, Chase, OCO, bracket, TWAP, VWAP, iceberg, protection, time-in-force, and trailing-stop concepts. OpenAPI remains authoritative for which fields are legal in each discriminated request variant.