Order Types, Fields, and Lifecycle in Kairos Explained

Prefer WebSocket for order submission. Placing and cancelling orders over the persistent /ws socket is lower-latency (one round trip instead of the REST submit/poll pair) and simpler to build: one connection, one auth handshake, and pushed order_update/fill events instead of polling. See Order Execution over WebSocket.

Kairos provides a unified order entry layer that abstracts the differences between venue order models. You submit orders through a single Execution API, and Kairos handles the translation, routing, and signature requirements for each underlying venue. This page covers how orders are structured, how they move through their lifecycle, and how to cancel them when needed.

Order Types

Kairos supports two fundamental order types across prediction market venues:

Limit Orders

You specify a maximum buy price or minimum sell price. The order rests on the order book until it matches or you cancel it. Most prediction market venues only support limit orders.

Market Orders

You accept the best available price immediately. Market orders fill against the existing book and do not rest. Availability depends on venue capabilities — check supports_market_orders before submitting.

Key Order Fields

Every order you submit includes a standard set of fields. The table below describes each one:

Field	Type	Required	Description
`exchange`	string	✅	Venue to route to: `polymarket`, `kalshi`, `predictfun`, `opinion`
`market_id`	string	✅	The market’s canonical ID or venue-native ID
`contract_id`	string	✅	The specific outcome contract/token to trade
`side`	enum	✅	`BUY` or `SELL`
`price`	decimal	✅ (limit)	Limit price between 0.01 and 0.99, must conform to tick grid
`size`	decimal	✅	Number of shares / contracts
`order_type`	enum	✅	`limit` or `market`
`time_in_force`	enum		`GTC` (Good-Til-Cancelled), `IOC` (Immediate-or-Cancel), `FOK` (Fill-or-Kill)
`client_order_id`	string		Your own idempotency key — Kairos deduplicates on this

Example Order Payload

{
  "exchange": "polymarket",
  "market_id": "0xdef456...",
  "contract_id": "0xabc123...",
  "side": "BUY",
  "price": 0.62,
  "size": 100,
  "order_type": "limit",
  "time_in_force": "GTC",
  "client_order_id": "my-order-001"
}

Submit it with POST /orders:

curl -X POST https://execution.kairos.trade/orders \
  -H "X-Client-Id: $KAIROS_CLIENT_ID" \
  -H "X-Api-Key: $KAIROS_API_KEY" \
  -H "X-Api-Secret: $KAIROS_API_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "exchange": "polymarket",
    "market_id": "0xdef456...",
    "contract_id": "0xabc123...",
    "side": "BUY",
    "price": 0.62,
    "size": 100,
    "order_type": "limit",
    "time_in_force": "GTC"
  }'

Order Lifecycle

Once submitted, an order moves through the following states:

Open

The order has been accepted by the venue and is resting on the order book, waiting for a counterparty at your price.

Partially Filled

Some — but not all — of your requested size has been matched. The unfilled remainder continues to rest on the book (for GTC orders).

Filled

The full order size has been matched. Your position is updated and collateral is debited/credited accordingly.

Cancelled

The order was removed from the book — either by you explicitly, by a cancel-all call, or because it expired (IOC/FOK with no fill).

Checking Order Status

Fetch a single order by its Kairos-assigned ID:

curl https://execution.kairos.trade/orders/ord_abc123xyz \
  -H "X-Client-Id: $KAIROS_CLIENT_ID" \
  -H "X-Api-Key: $KAIROS_API_KEY" \
  -H "X-Api-Secret: $KAIROS_API_SECRET"

{
  "order_id": "ord_abc123xyz",
  "client_order_id": "my-order-001",
  "exchange": "polymarket",
  "side": "BUY",
  "price": 0.62,
  "size": 100,
  "filled_size": 45,
  "remaining_size": 55,
  "status": "partially_filled",
  "created_at": "2025-01-15T10:23:00Z",
  "updated_at": "2025-01-15T10:24:12Z"
}

List all your open orders with GET /orders.

Fee Quotes

Before submitting an order, request a combined platform + venue fee quote so you know the exact cost:

curl "https://execution.kairos.trade/orders/fee-quote?exchange=polymarket&side=BUY&price=0.62&size=100" \
  -H "X-Client-Id: $KAIROS_CLIENT_ID" \
  -H "X-Api-Key: $KAIROS_API_KEY" \
  -H "X-Api-Secret: $KAIROS_API_SECRET"

{
  "platform_fee": 0.001,
  "exchange_fee": 0.002,
  "total_fee": 0.003,
  "fee_currency": "pUSD"
}

Always fetch a fee quote before displaying a trade confirmation UI to your users. Fees vary by venue and can differ between maker and taker.

Hosted vs Self-Custody Execution

Kairos offers two execution modes for on-chain venues (Polymarket, Predict.fun, Opinion):

Hosted (v1 endpoints)
Self-Custody (v2 endpoints)

Kairos holds signing keys on your behalf. You call POST /orders and Kairos signs and submits the on-chain transaction for you. This is the simplest integration path.

curl -X POST https://execution.kairos.trade/orders \
  -H "X-Client-Id: $KAIROS_CLIENT_ID" \
  -H "X-Api-Key: $KAIROS_API_KEY" \
  -H "X-Api-Secret: $KAIROS_API_SECRET" \
  -H "Content-Type: application/json" \
  -d '{ "exchange": "polymarket", ... }'

You retain control of your private key. Kairos builds an unsigned EIP-712 payload; you sign it with your wallet and return the signature. Kairos then submits it to the venue.Step 1 — Build the intent:

curl -X POST https://execution.kairos.trade/v2/orders/intent \
  -H "X-Client-Id: $KAIROS_CLIENT_ID" \
  -H "X-Api-Key: $KAIROS_API_KEY" \
  -H "X-Api-Secret: $KAIROS_API_SECRET" \
  -H "Content-Type: application/json" \
  -d '{ "exchange": "polymarket", "side": "BUY", "price": 0.62, "size": 100, ... }'

Step 2 — Sign and submit:

curl -X POST https://execution.kairos.trade/v2/orders/submit \
  -H "X-Client-Id: $KAIROS_CLIENT_ID" \
  -H "X-Api-Key: $KAIROS_API_KEY" \
  -H "X-Api-Secret: $KAIROS_API_SECRET" \
  -H "Content-Type: application/json" \
  -d '{ "intent_id": "int_xyz789", "signature": "0x..." }'

EIP-712 Signing

For self-custody orders, Kairos returns a structured EIP-712 typed data object from /v2/orders/intent. Sign it with your wallet using eth_signTypedData_v4 and pass the resulting hex signature to /v2/orders/submit.

// Using ethers.js
const intent = await kairos.buildIntent({ exchange: "polymarket", ... });

const signature = await signer._signTypedData(
  intent.domain,
  intent.types,
  intent.message
);

await kairos.submitOrder({ intent_id: intent.intent_id, signature });

EIP-712 signing keeps your private key off Kairos servers entirely. The signature is mathematically bound to the exact order parameters — it cannot be modified after signing.

Cancelling Orders

Cancel a single order

curl -X POST https://execution.kairos.trade/orders/ord_abc123xyz/cancel \
  -H "X-Client-Id: $KAIROS_CLIENT_ID" \
  -H "X-Api-Key: $KAIROS_API_KEY" \
  -H "X-Api-Secret: $KAIROS_API_SECRET"

Cancel a specific set of orders atomically

Use POST /orders/cancel-batch to cancel multiple order IDs in a single atomic operation at the routing layer:

curl -X POST https://execution.kairos.trade/orders/cancel-batch \
  -H "X-Client-Id: $KAIROS_CLIENT_ID" \
  -H "X-Api-Key: $KAIROS_API_KEY" \
  -H "X-Api-Secret: $KAIROS_API_SECRET" \
  -H "Content-Type: application/json" \
  -d '{ "order_ids": ["ord_abc123", "ord_def456", "ord_ghi789"] }'

Cancel all open orders on a venue

curl -X POST https://execution.kairos.trade/orders/cancel-all \
  -H "X-Client-Id: $KAIROS_CLIENT_ID" \
  -H "X-Api-Key: $KAIROS_API_KEY" \
  -H "X-Api-Secret: $KAIROS_API_SECRET" \
  -H "Content-Type: application/json" \
  -d '{ "exchange": "polymarket" }'

cancel-all cancels every open order you have on the specified exchange. There is no undo. Confirm the exchange value carefully before calling this endpoint.

Cross-Venue Routing

When the same market exists on multiple venues (e.g., matched on both Polymarket and Kalshi), Kairos can split your order across both legs automatically. This lets you fill larger sizes than any single venue’s book can absorb. Step 1 — Price the route:

curl "https://execution.kairos.trade/orders/route-quote?link_id=<link_id>&side=BUY&size=500" \
  -H "X-Client-Id: $KAIROS_CLIENT_ID" \
  -H "X-Api-Key: $KAIROS_API_KEY" \
  -H "X-Api-Secret: $KAIROS_API_SECRET"

The response shows the expected fill price and per-leg breakdown. If the route looks good, execute it: Step 2 — Execute the routed buy:

curl -X POST https://execution.kairos.trade/orders/route-buy \
  -H "X-Client-Id: $KAIROS_CLIENT_ID" \
  -H "X-Api-Key: $KAIROS_API_KEY" \
  -H "X-Api-Secret: $KAIROS_API_SECRET" \
  -H "Content-Type: application/json" \
  -d '{ "link_id": "<link_id>", "side": "BUY", "size": 500 }'

Use GET /orders/routes to list your open routed parent orders and track each leg’s fill status.

Synthetic Books

Kairos can create a Synthetic Book — a virtual order book that combines liquidity across multiple related markets or venues. Synthetic books are useful for cross-venue arbitrage strategies and unified pricing views. Create or join a Synthetic Book definition with POST /v1/synthetics. Inspect an existing one with GET /v1/synthetics/{synthetic_id}. Leases expire and must be refreshed with POST /v1/synthetics/subscriptions/{subscription_id}/refresh.

Combos and Parlays

For Polymarket, Kairos supports combo orders — multi-leg parlays where you take a position on multiple independent outcomes simultaneously. Get a quote without executing with POST /combo/quote, then execute with POST /combo/execute. Manage open positions with GET /combo/positions.

Current Position Exposure

Check your live position exposure across all open orders and fills:

curl https://execution.kairos.trade/positions/exposure \
  -H "X-Client-Id: $KAIROS_CLIENT_ID" \
  -H "X-Api-Key: $KAIROS_API_KEY" \
  -H "X-Api-Secret: $KAIROS_API_SECRET"

Get Started

Core Concepts

Learn Trading

Guides

Perpetual Futures

External Execution

Trading

Compliance

Updates

Order Types, Fields, and Lifecycle in Kairos Explained

Order Types

Limit Orders

Market Orders

Key Order Fields

Example Order Payload

Order Lifecycle

Checking Order Status

Fee Quotes

Hosted vs Self-Custody Execution

EIP-712 Signing

Cancelling Orders

Cancel a single order

Cancel a specific set of orders atomically

Cancel all open orders on a venue

Cross-Venue Routing

Synthetic Books

Combos and Parlays

Current Position Exposure

​Order Types

Limit Orders

Market Orders

​Key Order Fields

​Example Order Payload

​Order Lifecycle

​Checking Order Status

​Fee Quotes

​Hosted vs Self-Custody Execution

​EIP-712 Signing

​Cancelling Orders

​Cancel a single order

​Cancel a specific set of orders atomically

​Cancel all open orders on a venue

​Cross-Venue Routing

​Synthetic Books

​Combos and Parlays

​Current Position Exposure

Order Types

Key Order Fields

Example Order Payload

Order Lifecycle

Checking Order Status

Fee Quotes

Hosted vs Self-Custody Execution

EIP-712 Signing

Cancelling Orders

Cancel a single order

Cancel a specific set of orders atomically

Cancel all open orders on a venue

Cross-Venue Routing

Synthetic Books

Combos and Parlays

Current Position Exposure