Orders & OMS
Orders are intents. You submit what you want; the platform composes, signs,
and dispatches it to the venue, then reports the outcome over
/ws/risk. One endpoint set covers every wired venue.
Every write on this page needs a non-readonly credential. cancel,
cancel-all, and flatten accept liquidation; everything else — place,
modify, reverse, chase, and the bracket calls — needs fullTrading. The rule
is that liquidation may reduce exposure, never add it. A readonly
credential is refused with 403 tier_readonly, a liquidation credential on a
fullTrading route with 403 tier_insufficient. See
Scopes & tiers.
Place an intent
Section titled “Place an intent”POST /api/v1/oms/intents
curl -s https://api.troncharts.xyz/api/v1/oms/intents \ -H "authorization: Bearer $TOKEN" \ -H "x-tenant-slug: $TC_TENANT_SLUG" \ -H 'content-type: application/json' \ -H "idempotency-key: $(uuidgen)" \ -d '{ "venue": "paper", "symbol": "BTC.HL", "side": "buy", "type": "limit", "qty": "0.01", "price": "60000", "timeInForce": "Gtc" }'| Field | Notes |
|---|---|
venue |
Required. paper today. The schema also lists hyperliquid, aster, polymarket and kalshi, which are refused with 403 live_accounts_disabled while live execution is off. |
symbol |
Required, venue-suffixed (BTC.HL). From the Nuntius symbol catalog (Market data). Round qty to its qtyStep and every price to its tick (The symbol catalog). A Hyperliquid symbol the venue does not list is 400 unknown_symbol; a listed symbol with no fresh price yet is 503 mark_unavailable, which is worth a retry. |
side |
buy / sell. |
type |
market, limit, stop, stop_limit, take_profit. |
qty |
Required. Decimal string preferred. |
price |
Required for limit. |
triggerPrice |
Required for stop, stop_limit, take_profit. |
stopLimitPrice |
Ignored on paper. The resting limit of a stop_limit is price (omitting it is 400 price_required). |
reduceOnly |
Never increases exposure. |
timeInForce |
Gtc / Ioc / Alo. |
leverage |
Whole number. Checked at compose time against the effective cap — see Leverage. |
accountId |
Optional — defaults to the credential’s active account. Set it to place on a specific owned account. |
clientOrderId |
Your own correlation id, echoed back on the response and on the WS frames. |
Sandbox orders go in as venue: "paper" against a paper account.
The same paper sentinel accepts market-data-only T4 symbols and USD-quoted
LSE symbols. See the
API contract for the symbol-specific restrictions.
GET /api/v1/venues is capability discovery — the adapters wired in this
deploy and what each one supports. It is not this enum: b3 is listed there
but compose rejects it (paper B3 orders go in as paper), and paper is never
listed there.
The response carries the intent id. On paper a marketable order fills
synchronously, so the 201 also carries the outcome:
{ "intentId": "3f2a…", "state": "filled", "clientOrderId": "my-42", "syncFill": { "qty": "0.01", "avgPrice": "64210.5" } }A resting order comes back without syncFill. Re-sending the same
clientOrderId with the same order returns the original intent with 200
instead of placing a second one; the same clientOrderId with a different
order is 409 client_order_id_conflict. Subscribe to the Order-Intent-Changed
topic on /ws/risk and match Order-Intent-Update frames by their intentId
— they carry the venue order id, the last event, and the terminal state.
Cancel, modify, and the bulk operations
Section titled “Cancel, modify, and the bulk operations”| Endpoint | Does |
|---|---|
POST /api/v1/oms/cancel |
Cancel one working order by venueOrderId — the venue’s id, not the intent id. Read it from GET /api/v1/accounts/{id}/orders or the Open-Orders-Update frames. |
POST /api/v1/oms/modify |
Replace a working order’s price, qty, or trigger by intentId. Resolves a new intent id. |
POST /api/v1/oms/cancel-all |
Cancel every working order on the account. |
POST /api/v1/oms/flatten |
Close every open position on the account. |
POST /api/v1/oms/reverse |
Close a position and open the opposite side. |
POST /api/v1/oms/chase |
Cancel-and-replace toward the touch. |
curl -s https://api.troncharts.xyz/api/v1/oms/cancel \ -H "authorization: Bearer $TOKEN" -H 'content-type: application/json' \ -H "x-tenant-slug: $TC_TENANT_SLUG" \ -H "idempotency-key: $(uuidgen)" \ -d '{ "venueOrderId": "…" }'await sdk.oms.modify({ intentId, newPrice: 59500 }, idempotencyKey)Modify takes newPrice, newQty, newTriggerPrice, and newStopLimitPrice.
Unlike compose, these are numbers only — a decimal string is rejected.
Brackets
Section titled “Brackets”There is no inline bracket field on compose. Place the entry, then attach the OCO legs:
| Endpoint | Does |
|---|---|
POST /api/v1/oms/brackets/attach |
Attach TP and/or SL to an entry by parentIntentId. |
POST /api/v1/oms/brackets/attach-to-position |
Attach to an already-open position. |
POST /api/v1/oms/brackets/modify |
Move an existing leg. |
curl -s https://api.troncharts.xyz/api/v1/oms/brackets/attach \ -H "authorization: Bearer $TOKEN" -H 'content-type: application/json' \ -H "x-tenant-slug: $TC_TENANT_SLUG" \ -d '{ "parentIntentId": "…", "tpPrice": 64000, "slPrice": 58000 }'At least one of tpPrice, tpLegs or slPrice must be set; sending none is
400 no_legs_requested.
A TP that is already marketable fills as soon as it is attached. When that fill
closes the position, the other legs are its OCO siblings: they are cancelled
before reaching the venue, and the answer is still 200, with their ids in
ocoCanceledIntentIds and the intents in canceled
(reason: oco_sibling_filled).
tpLegs is the scale-out ladder — up to three rungs, each
{ price, qty, tag? } with tag one of tp1 / tp2 / tp3, and mutually
exclusive with tpPrice. It is accepted on both attach routes:
{ "parentIntentId": "…", "tpLegs": [ { "price": 64000, "qty": 0.5, "tag": "tp1" }, { "price": 66000, "qty": 0.5, "tag": "tp2" } ], "slPrice": 58000}On attach-to-position the rung quantities are read as ratios of the
position, not absolute sizes — see
Place a scale-out ladder. When the parent is still
unfilled the response carries staged: true — the legs arm on fill.
Venue-specific fields
Section titled “Venue-specific fields”Some venues accept extras: asterTimeInForce, asterKind, clientId. They
are ignored by venues that don’t use them, but read GET /api/v1/venues for
what each adapter actually supports rather than sending them blind.
Leverage
Section titled “Leverage”Pass leverage on the intent itself. It is validated at compose time against
the effective per-venue cap, which comes from the account’s trading group —
groups scope fee schedules, leverage caps, and venue/symbol allowlists — and is
never above the venue’s own maximum. An intent above the cap is rejected at
compose with 422 leverage_above_cap (the body carries the numeric cap and
requested), before anything reaches the venue; a fraction is a
400 leverage_not_integer, and anything above 1000 fails schema validation
first (400 invalid_body). Read the cap (and the default) for a
symbol from GET /api/risk/limits?venue=&symbol=.
- Omit
leverageto use the configured default. reduceOnlyorders and outcome shares ignore it: a close is never refused for its leverage.- On a paper account the order’s leverage margins the position it opens. An order that adds to an open position keeps that position’s leverage.
- Per-asset leverage on live accounts is in development. See Paper-only mode.