Orders

List the authenticated user's orders

Returns orders belonging to the authenticated caller, most recent first, with optional status filtering and offset pagination. When status is omitted, every status (including terminal ones) is returned. Response is trimmed. To keep this endpoint cheap for polling UIs, the heavy raw (full venue response, can be ~100 KB/order) and metadata fields are stripped from every row (raw: null, metadata: null); the outcome label is preserved by falling back to metadata.outcome before stripping. Use GET /orders/{order_id} for the full row including raw. Auth & scope. Requires trade:read. For API-key callers without an exchange_id filter, every distinct provider the user has orders on is checked for API-key access before the list is returned.

get/orders

Request

Base URL
https://execution.kairos.trade
Auth
API key in header X-Client-Id and API key in header X-Api-Key and API key in header X-Api-Secret

Query parameters

exchange_idstring

Example:polymarket

Filter to a single venue (e.g. polymarket, kalshi, hyperliquid).

statusstring

Example:live,partial

A single status or a comma-separated set, e.g. filled or open,pending,live,partial. Omit to return all statuses. Matched against the RAW stored status strings, which are not identical to the OrderStatus enum: queued/locked/executing/orphaned are all stored as pending, and the stored set additionally includes open, processing and delayed.

active_onlyboolean

When true, return only working orders — stored status in pending, queued, locked, processing, executing, live, open, partial or delayed, excluding a partial market/FAK/IOC/FOK order (which is terminal in practice).

limitinteger

Example:50

Maximum rows to return. Clamped to at most 500 server-side. There is no lower clamp, so a zero or negative value is passed through to the query — send a positive value.

offsetinteger

Rows to skip, for paginating order history. Clamped to >= 0. Ignored when before_id is set — the two pagination modes are mutually exclusive.

before_idstring uuid

Keyset cursor on (submitted_at, id) — return rows strictly older than this order. Preferred over offset for deep pagination; takes precedence over it.

Response

The caller's orders (raw/metadata stripped), newest first.

idstring uuid required

Internal Kairos order id.

user_idstring required

Owning user's id.

exchange_idstring required

Venue identifier (e.g. polymarket, kalshi, predictfun, hyperliquid).

market_idstring required

Market/contract identifier on the venue (condition id for Polymarket; numeric HIP-4 outcome id for Hyperliquid).

token_idstring nullable

Outcome-token id. Hyperliquid uses a side coin such as #1010 or #1011.

side'buy' | 'sell' required

Order/intent side. Lower-case on the wire.

kind'market' | 'limit' required

Order type. market orders still require a price (the limit you'll cross to); limit orders rest at price until filled or cancelled.

quantitystring required

Order quantity (decimal string, full precision), shares/contracts.

pricestring nullable

Limit price as a decimal string in [tick, 1] (prediction-market venues).

price_bpsinteger nullable

price expressed in basis points (price × 10000), for DB/analytics compatibility.

time_in_force'GTC' | 'GTD' | 'FOK' | 'FAK' | 'IOC' required

Time-in-force, always UPPER-CASE on the wire. GTC/GTD are resting (limit-style); FOK/FAK/IOC are immediate taker executions.

post_onlyboolean

Whether this order was submitted maker-only. A post-only order is one the venue was told to REJECT rather than let cross the spread and take liquidity. Always present; false for ordinary orders and for venues with no post-only concept.

expires_atstring date-time nullable

Expiration timestamp for GTD orders.

filled_quantitystring required

Cumulative filled quantity (decimal string).

avg_fill_pricestring nullable

Size-weighted average fill price (decimal string, 0..1), null until any fill lands.

avg_fill_price_bpsinteger nullable

avg_fill_price in basis points.

exchange_order_idstring nullable

Venue-assigned order handle. Null until the order reaches the venue.

Lifecycle status. partial is the wire spelling of a partially-filled order (NOT partially_filled).

The internal states queued, locked and orphaned are persisted as pending, so an order read back from GET /orders or GET /orders/{order_id} reports pending for all three — they are listed here because they are part of the type and can appear on in-process/streamed values. executing is the exception: once a worker claims the order for submission it is persisted as executing, and read-back endpoints report executing until the venue acknowledges (then live) or the attempt fails. The one place a caller sees queued directly is the status field of a fresh POST /orders response, which is the literal string "queued".

created_atstring date-time required

updated_atstring date-time required

locked_bystring nullable

Worker id currently holding the execution lock, if any.

lock_expires_atstring date-time nullable

error_messagestring nullable

Failure detail when status is failed.

fee_amountstring nullable

Fee charged for this order, decimal string.

fee_currencystring nullable

client_order_idstring nullable

Caller-supplied idempotency key, if one was provided at submission.

wallet_idstring nullable

FK to the user's wallet used for this order.

outcomestring nullable

Human-readable outcome label (e.g. "Yes", "No", a team name).

outcome_idstring nullable

Outcome id — equals token_id on Polymarket.

trigger_pricestring nullable

Trigger price for stop-loss/take-profit style orders, decimal string.

trigger_price_bpsinteger nullable

gas_sponsoredboolean required

Whether Kairos sponsored gas for this order (always false on the self-custody external-signing lane).

collateral_mode'skip' | 'check' | 'fund' required

The collateral mode resolved for this order at submit. Always present; skip for an order that asked for nothing.

shard_fundingboolean required

Whether the Kalshi shard move was permitted for this order. Always present; true unless the caller opted out.

max_bridge_fee_usdcstring nullable

The order's bridge-fee ceiling in USDC, decimal string. Only ever set under collateral_mode=fund.

max_funding_wait_msinteger nullable

The order's funding-wait ceiling in milliseconds. Only ever set under collateral_mode=fund.

gas_amountstring nullable

Gas spent, decimal string, if applicable.

maker_addressstring nullable

On-chain maker/signer address, for Polymarket reconciliation.

tx_hashstring nullable

On-chain transaction hash (Polygon), if the fill involved one.

rawunknown

bot_idstring nullable

Trading-bot id that placed this order, if any (null for manual/API orders).

sourcestring nullable

Attribution for who initiated the order: manual (web UI), bot, copytrade, api (API-key auth), or fastlane (external-signing lane).

metadataunknown

holding_walletstring required

On-chain wallet that holds (or will hold) the resulting shares — the EOA for legacy Polymarket orders, or the Safe deposit-wallet proxy for upgraded/external-signing users. Empty string for non-Polymarket orders.

Example response

[
  {
    "exchange_id": "polymarket",
    "side": "buy",
    "kind": "limit",
    "quantity": "100",
    "price": "0.52",
    "price_bps": 5200,
    "time_in_force": "GTC",
    "filled_quantity": "0",
    "status": "live",
    "failure": {
      "code": "FOK_NOT_FILLED",
      "details": {
        "code": "FUNDS_INSUFFICIENT_USDC",
        "actions": [
          {
            "label": "Add Funds"
          }
        ]
      }
    },
    "collateral_mode": "skip",
    "shard_funding": true,
    "source": "api"
  }
]

Changes

No recorded changes to this operation across all 1 revision of this API.