Skip to main content
POST
Submit a new order
Before you submit
  • price is required on every order, including market orders — it is the limit you are willing to cross, not a sentinel.
  • quantity must be positive. API-key BUYs also have a minimum notional.
  • Prefer the WebSocket order execution guide: one persistent connection, one round trip, and pushed fills instead of polling.

Authorizations

​
X-Client-Id
string
header
required

Credential client id (kairos_ck_...). Must be sent together with X-Api-Key and X-Api-Secret.

​
X-Api-Key
string
header
required

64-char hex API key.

​
X-Api-Secret
string
header
required

64-char hex API secret.

Body

application/json

Body for POST /orders (custodial order submission).

​
exchange_id
string
required

Venue identifier, must be a registered exchange (e.g. polymarket, kalshi, predictfun, hyperliquid).

Example:

"polymarket"

​
market_id
string
required

Market/contract identifier on the venue. Hyperliquid expects the numeric HIP-4 outcome id.

​
side
enum<string>
required

buy or sell, case-insensitive on input.

Available options:
buy,
sell,
BUY,
SELL,
Buy,
Sell
Example:

"buy"

​
kind
enum<string>
required

market or limit, lower-case exactly.

Available options:
market,
limit
Example:

"limit"

​
quantity
string
required

Decimal string, shares/contracts. Must be > 0 and <= 1,000,000. A minimum order size (default 1.0, MIN_ORDER_QUANTITY) applies to BUY orders only — SELL/close orders are allowed at any size so a position can be fully closed after partial fills. API-key-authenticated BUYs additionally require quantity × price >= $5 notional; session-JWT callers and all SELLs are exempt.

Example:

"100"

​
user_id
string
deprecated

Ignored. The authenticated caller's id is always used.

​
token_id
string | null

Outcome-token id. For Hyperliquid, pass the selected side coin #<10 * market_id + side_index>; it is required to select side 1.

​
outcome
string | null

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

Example:

"Yes"

​
price
string

Decimal string, REQUIRED for every order (including market orders, where it is the limit you're willing to cross to). Must be > 0 and <= the venue's max price (typically 1.0 for prediction markets).

Example:

"0.52"

​
time_in_force
string
default:GTC

GTC, GTD, FOK, FAK, or IOC (case-insensitive on input, normalized to upper-case). Defaults to GTC if omitted; an unrecognized non-empty value is rejected rather than silently downgraded to GTC. Must be a TIF the target venue's capabilities advertise.

Example:

"GTC"

​
post_only
boolean | null
default:false

Maker-only. When true the venue must REJECT the order rather than let any part of it cross the spread and take liquidity — it is a guarantee, never a hint, so an order that cannot honour it is rejected instead of being downgraded to a taker. Requires kind=limit and time_in_force of GTC or GTD, on a venue whose capabilities advertise post-only support (currently Polymarket, Kalshi, Predict.fun and Hyperliquid — the last expresses maker-only as its Alo time-in-force rather than a flag, but the request field is the same). Any other combination is a 400. Defaults to false.

Example:

false

​
expiration_minutes
integer | null

Minutes from now until expiry. Only meaningful (and validated) when time_in_force=GTD: must be in [1, 43200] (30 days).

Example:

60

​
trigger_price
string | null

Decimal string. Trigger price for stop-loss/take-profit style orders. Must be > 0 and, like price, <= the venue's max price.

​
collateral
enum<string> | null
default:skip

How much of the collateral router runs for this order. skip (the server default) is today's path: no affordability check, no hold, no router call, zero added latency. check places an affordability check and a hold and refuses a known shortfall, but never moves money. fund is check plus cross-ledger funding inside the two caps below, and REQUIRES both of them. An unrecognised value is rejected 400 naming the three valid values; it is never downgraded to skip.

Available options:
skip,
check,
fund
Example:

"skip"

​
shard_funding
boolean | null
default:true

Kalshi only. Move collateral between the account's own Kalshi shards before submit. Defaults to true — same venue, zero fee, one REST call, and already every account's behaviour — so an existing caller is unaffected. Send false to skip it.

Example:

true

​
max_bridge_fee_usdc
string | null

Decimal string. The most bridge fee this order consents to pay, in USDC. Required when collateral=fund and rejected 400 otherwise; 0 is a valid cap meaning "fund only if it is free".

Example:

"1.50"

​
max_funding_wait_ms
integer | null

The longest this order consents to wait for funding, in milliseconds. Required when collateral=fund and rejected 400 otherwise.

Example:

30000

​
gas_sponsored
boolean | null

Requests gas sponsorship. Currently not implemented server-side.

​
client_order_id
string | null

Caller-supplied idempotency key. A retry with the same (user, exchange_id, market_id, client_order_id) returns the existing order instead of creating a duplicate, and does not consume a rate-limit slot. If omitted, a random id is generated server-side (so un-keyed retries are NOT deduped).

​
orderbook_levels
string[][]
deprecated

Ignored. The executor always fetches fresh orderbook data itself. Kept only for backwards-compatible request bodies.

​
max_slippage
string | null
deprecated

Deprecated — use max_slippage_cents. Decimal in [0, 0.5] (e.g. 0.10 = 10%).

​
max_slippage_cents
integer | null

Maximum acceptable slippage in cents. Must be in [1, 99] if provided.

Example:

5

​
max_retries
integer | null

Maximum retry attempts for transient failures. Defaults to 0.

​
bot_id
string | null

Trading-bot id this order is attributed to.

​
source
string | null

Order-source attribution override. Pass copytrade explicitly when relevant; otherwise the server derives it from the auth method (API-key auth → api, bot_id present → bot, else → manual).

Example:

"api"

Response

Order accepted, persisted, and enqueued for execution. Does not imply the order is live on the venue yet — poll or subscribe to /ws for the terminal state.

Response for POST /orders.

​
order_id
string<uuid>
required

Internal Kairos order id. Use with GET /orders/{order_id} and the cancel endpoints.

​
status
string
required

queued for a newly-created order; on an idempotent replay (matching client_order_id), the pre-existing order's current status (pending, live, partial, filled, cancelled, expired, or failed).

Example:

"queued"

​
funding
object | null

What the collateral router did for this order. null whenever no funding work ran — every skip order, and every order while funding orchestration is still being built.