Skip to content

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.

POST /api/v1/oms/intents

Terminal window
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.

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.
Terminal window
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.

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.
Terminal window
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.

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.

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 leverage to use the configured default.
  • reduceOnly orders 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.