Skip to main content
POST

Authorizations

​
X-API-KEY
string
header
required

Per-user API key. Create and revoke keys from your SOAR account settings. A revoked key stops working within 60 seconds.

Body

application/json

Supplying both ticker and market_id is 400 conflicting_identifiers rather than a guessed winner — a caller that sends two identifiers does not know which one it means, and guessing on a trading request is the wrong kind of helpful. The same rule sizes the order: exactly one of qty (shares) or budget_cents (cash), and both at once is 400 invalid_budget.

​
outcome
enum<string>
required

Which side of the market. Your position is in this outcome.

unknown is emitted only for a stored value this API version does not recognise (corruption, or an encoding added after your client was generated). It is declared so one bad row cannot fail the whole page; treat it as unparseable data rather than a fourth outcome.

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

See Outcome for when unknown appears.

Available options:
buy,
sell,
unknown
​
price
integer
required

Limit price in whole cents, for the outcome you named. On a budget order this is your worst acceptable per-share price — a pure slippage bound; fills execute at the resting prices, which may be better.

Required range: 1 <= x <= 99
​
client_order_id
string
required

Your idempotency key: 1–64 printable ASCII characters, unique per user (two users may safely use the same value). Re-sending the same one returns the same order rather than placing a second, which is what makes it the correct response to a result_unknown 503.

Required string length: 1 - 64
​
ticker
string

The market, by ticker. Send this or market_id, not both.

​
market_id
string<uuid>

The market, by UUID. Send this or ticker, not both.

​
qty
integer

Whole shares. Send this or budget_cents, not both — an order is denominated in shares or in cash, never both at once.

Required range: x >= 1
​
budget_cents
integer

A budget-denominated taker buy: "spend this many cents" instead of "buy this many shares". The engine sizes the order against the live book inside the match step, spending up to min(budget_cents, your available cash) including taker fees — there is no client-side dollars→shares conversion, so the budget is consumed exactly (to within one share at your price bound).

Requires side: buy and time_in_force ioc or fok — a budget order never rests, because its derived size is only meaningful against the book it was sized on. fok fills the full affordable size or rejects 422 budget_not_fillable when the book cannot absorb the budget within your price bound; ioc executes whatever is eligible and stops. The response's qty/filled_qty carry the engine-derived executed size and spent_cents the exact realized cost.

Required range: x >= 1
​
time_in_force
enum<string>

Defaults to gtc. Budget orders must be ioc or fok.

Available options:
gtc,
ioc,
fok,
unknown

Response

The engine applied the order.

​
order_id
string
required

Decimal digits in a string. It is FNV-derived and routinely exceeds 2^53, so a JSON number would be silently rounded by any JavaScript client and you would then cancel an order that does not exist.

Pattern: ^[0-9]{1,20}$
​
ticker
string
required

This market's ticker.

​
market_id
string<uuid>
required
​
event_ticker
string
required

The parent event's ticker — the prefix this market's ticker begins with.

​
outcome
enum<string>
required

Which side of the market. Your position is in this outcome.

unknown is emitted only for a stored value this API version does not recognise (corruption, or an encoding added after your client was generated). It is declared so one bad row cannot fail the whole page; treat it as unparseable data rather than a fourth outcome.

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

See Outcome for when unknown appears.

Available options:
buy,
sell,
unknown
​
price
integer
required

Your limit price in whole cents, for your own outcome.

Required range: 1 <= x <= 99
​
qty
integer
required

Original size in shares.

Required range: x >= 0
​
remaining_qty
integer
required
Required range: x >= 0
​
filled_qty
integer
required
Required range: x >= 0
​
status
enum<string>
required

accepted is a transient projection state visible only on reads, while the durable state catches up. A create or amend response never returns it: its status is derived from what the engine actually did.

Available options:
accepted,
open,
partially_filled,
filled,
canceled,
expired
​
time_in_force
enum<string>
required

gtc rests until filled or canceled. ioc fills what it can immediately and cancels the rest. fok fills entirely or not at all. Omitted means gtc — an order that would silently become ioc dies the moment it fails to cross.

Available options:
gtc,
ioc,
fok,
unknown
​
created_at
string<date-time>
required

On a read, when the engine sequenced the order. On a create or amend response, the gateway's submit instant instead — the engine's reply carries no timestamp, and the authoritative one is only visible to the projection. The two are within a millisecond, but they are not the same clock: re-sending an idempotent client_order_id returns the same order with a fresh created_at. Key on order_id, not on this.

​
updated_at
string<date-time>
required
​
client_order_id
string

Echoed on the create response when you supplied one. Not stored, so it is absent from every read (GET /orders, GET /orders/{order_id}) — keep your own mapping. order_id is derived deterministically from it, so re-sending the identical create is also a safe way to recover the id.

Maximum string length: 64
​
reserved_cents
integer

Cash locked by this order. Present on reads only — a create or amend response omits it, because the engine reports the caller's account-wide reserve there rather than this order's share, and one field name cannot mean both. For the account-wide figure use reserved_cents on /portfolio/balance.

Required range: x >= 0
​
spent_cents
integer

Present only on the create response of a budget order: the exact realized cash cost of the execution — fill flow plus taker fees, cent for cent what left your balance. Absent on qty orders and on every read (the projection does not store it); reconcile historical executions against /portfolio/fills. On a budget order the executed size is qty (= filled_qty), so spent_cents / qty is your realized average cost per share, fees included.

Required range: x >= 1