Orders

Get a single order by internal id

Returns the full order row (including raw, the unredacted venue response, and metadata) for a single order the caller owns. Use this after POST /orders to poll a specific order's terminal state, or after GET /orders (which strips raw/metadata) to drill into one row.

get/orders/{order_id}

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

Path parameters

order_idstring uuid required

Internal Kairos order id (the order_id returned by POST /orders or POST /v2/orders/submit).

Response

The order, including raw and metadata.

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.