Skip to main content
POST
cURL

Authorizations

X-Api-Key
string
header
required

the key's id; public

X-Api-Secret
string
header
required

the key's secret (tl_live_…), shown once at creation; never log or share it

X-Client-Id
string
header
required

the key's own client id (cli_…), different for every key; public

Body

application/json
outcome
enum<string>
required

the venue's own outcome label the order is on

Available options:
yes,
no
side
enum<string>
required

buy or sell, the action on outcome

Available options:
buy,
sell
type
enum<string>
required

limit (rests at price or better, per time_in_force) or market (fills now against the book, up to an optional worst price)

Available options:
limit,
market
venue
enum<string>
required

the venue to trade on; only venues enabled for trading are accepted (no best-venue routing)

Available options:
kalshi,
polymarket,
limitless,
predictfun
amount_usd
string | null

buys only, instead of size: the USD to spend, at least 1, whole cents. A market buy spends it on Polymarket and predict.fun; elsewhere, and on a limit order, it buys the whole contracts it covers at price (or the worst price)

Required string length: 1 - 32
Pattern: ^[0-9]+(\.[0-9]{1,2})?$
client_order_id
string | null

an id you choose for this order (e.g. a UUID), unique per order; resend the same one only to retry the same order, which never places a second order. Optional: without it we generate one, and a retry of a lost answer may then place a second order

Pattern: ^[A-Za-z0-9_-]{1,64}$
expires_at
integer | null

GTD only, required with it: when the order expires, Unix seconds, at least 180 s and at most a year ahead

price
string | null

limit: the limit price of outcome, required. market: optional, the worst price you accept (a buy's ceiling, a sell's floor); without it the venue's extreme price is the bound and your limits count $1 per contract. A plain decimal string on the venue's grid, refused when off it, never rounded

Required string length: 1 - 32
Pattern: ^[0-9]+(\.[0-9]+)?$
size
integer | null

whole contracts, at least 5; a sell sends size, a buy sends size or amount_usd (exactly one)

Required range: 1 <= x <= 1000000
time_in_force
enum<string> | null

GTC rests until cancelled (the limit default); GTD rests until expires_at; FOK fills entirely now or not at all; FAK (alias IOC) fills what it can now and cancels the rest (the market default). A market order takes FOK or FAK/IOC only. Lower case is accepted

Available options:
GTC,
GTD,
FOK,
FAK,
IOC,
gtc,
gtd,
fok,
fak,
ioc
universal_id
string | null

the market universal id; its leg on venue is traded, so switching venue is one field. Send this, venue_market_id, or both

Required string length: 1 - 256
venue_market_id
string | null

the venue's own market id (on Kalshi, its ticker); with universal_id both must name the same leg, else 422, never re-routed

Required string length: 1 - 256

Response

a reconcile's answer (the venue's state, or not_placed), or a replay of the latest answer for this client_order_id

client_order_id
string
required

your id for this order

created_at
string
required

when we accepted the order, ISO 8601

id
string
required

our id for the order, ord_ and 24 hex digits; it exists from the moment we accept the request, so an order whose status is unknown has one too

Pattern: ^ord_[0-9a-f]{24}$
notional_reserved
string
required

the order's maximum loss counted against your limits, USD as a decimal string

outcome
string
required

the venue's own outcome label

side
enum<string>
required

buy or sell, the action on outcome at price

Available options:
buy,
sell
status
enum<string>
required

expired: a GTD order reached expires_at (filled_size says what filled first). unknown: the venue's answer was not received; retry with the same client_order_id or read GET /public/v1/orders/{id}, never send a new id. On a venue that cannot prove an order's absence it may stay unknown: check the venue before trading the same intent again

Available options:
open,
filled,
partially_filled,
cancelled,
expired,
unknown,
not_placed
time_in_force
enum<string>
required

as sent, or the type's default (GTC for limit, FAK for market)

Available options:
GTC,
GTD,
FOK,
FAK,
IOC,
gtc,
gtd,
fok,
fak,
ioc
type
enum<string>
required

limit or market, as sent

Available options:
limit,
market
universal_id
string | null
required

the market universal id holding the leg; null when no market lists it

updated_at
string
required

when we last recorded a change to the order, ISO 8601

venue
enum<string>
required

the venue the order was sent to

Available options:
kalshi,
polymarket,
limitless,
predictfun
venue_market_id
string
required

the venue's own market id the order went to

amount_usd
string | null

the USD amount sent, as sent; null when size was sent

avg_price
string | null

the average fill price of outcome, 0..1 as a decimal string, when the venue reported one

expires_at
integer | null

a GTD order's expiry, Unix seconds, as sent; null otherwise

filled_size
string | null

contracts filled, an exact decimal string; null while the status is unknown. A market buy, or a limit FAK/FOK buy, can fill more contracts than size at better prices (never spending more than size × price)

price
string | null

as sent: a limit order's price, a market order's worst price; null on a market order sent without one

remaining_size
string | null

contracts still resting, an exact decimal string; null while the status is unknown

size
integer | null

whole contracts ordered: as sent, or bought by amount_usd where the venue takes contracts; null when the venue took amount_usd itself

venue_market_title
string | null

the leg's title on the venue, when our mirror holds it

venue_order_id
string | null

the venue's order id; null while the status is unknown and for an order that was never placed

worst_price
string | null

a market order's bound as sent to the venue: your price, else the venue's extreme price; null on a limit order