Order lifecycle & signing
Placing an intent returns an intentId. Every account
trades paper today, so the platform fills the order and the intent moves on by
itself: you watch /ws/risk or read it back over REST.
There is nothing to sign. See Paper-only mode.
The socket is the fast path; the three reads below are for reconciliation — after a reconnect, after a timeout, or when you need the current state of one order without replaying frames.
Read one intent
Section titled “Read one intent”GET /api/v1/oms/intents/{intentId}
curl -s https://api.troncharts.xyz/api/v1/oms/intents/$INTENT_ID \ -H "authorization: Bearer $TOKEN"{ "id": "3f2a8c1e-0000-4000-8000-000000000001", "clientOrderId": "my-42", "accountId": "acc_0000000000000000", "walletAddress": "paper", "venue": "paper", "exchange": "paper", "symbol": "BTC.HL", "side": "buy", "type": "limit", "qty": "0.001000000000", "price": "60000.000000000000", "triggerPrice": null, "timeInForce": "Gtc", "reduceOnly": "false", "actionToSign": { "paper": true }, "dispatchEnvelope": { "paper": true }, "attestationHash": null, "state": "dispatched", "venueOrderId": "3f2a8c1e-0000-4000-8000-000000000001", "parentIntentId": null, "apiClientId": "cli_0000000000000000", "validUntil": "2026-11-17T18:44:27.012Z", "composedAt": "2026-11-16T18:44:27.012Z", "updatedAt": "2026-11-16T18:44:27.140Z"}| Field | Notes |
|---|---|
id |
The intentId you were handed at compose. |
clientOrderId |
Your own correlation id, when you sent one. |
qty, price, triggerPrice |
Decimal strings at stored precision (12 places). price is null on a market order. |
reduceOnly |
The string "true" or "false", as stored — compare it as a string. |
state |
Where the order is now; see States. |
venueOrderId |
The id POST /api/v1/oms/cancel takes. On paper it equals id. |
parentIntentId |
Set on bracket legs: the entry the leg belongs to. |
actionToSign, dispatchEnvelope |
Venue payloads. On paper both are { "paper": true }; nothing to act on. |
composedAt, updatedAt, validUntil |
ISO-8601 UTC with milliseconds. |
List your recent intents
Section titled “List your recent intents”GET /api/v1/oms/intents
curl -s https://api.troncharts.xyz/api/v1/oms/intents \ -H "authorization: Bearer $TOKEN"# → { "intents": [ { …same shape as above… }, … ] }The 50 most recent, newest first by composedAt. Add ?clientOrderId=my-42
to narrow the list to one correlation id. There is no paging: for older orders
read the account’s order history.
Recover an order by your clientOrderId
Section titled “Recover an order by your clientOrderId”GET /api/v1/oms/intents/by-client-order-id/{clientOrderId}
curl -s https://api.troncharts.xyz/api/v1/oms/intents/by-client-order-id/my-42 \ -H "authorization: Bearer $TOKEN"Use it when a POST /api/v1/oms/intents timed out before you saw the
intentId: if the order was placed, this returns it; a 404 means it was not.
It answers paper intents placed by the calling credential only, so it needs a
bearer token — a browser cookie session gets 403 bearer_required. Pair it
with sending a clientOrderId on every compose: re-sending the same compose
with the same clientOrderId returns the original intent instead of placing a
second order (see Orders & OMS).
Who sees what
Section titled “Who sees what”All three reads are scoped twice:
- Accounts. The account your credential is bound to and the accounts it
owns — the same set
GET /api/v1/accountslists — inside your tenant. A credential provisions accounts as children, so an intent placed on the sandbox account you just created is visible. - Credential. A bearer token sees only the intents its own credential composed, not every intent on the account. A browser cookie session sees every intent on its accounts.
An intent outside that scope answers 404 {"error":"not_found"}, never 403,
so the reads cannot be used to probe for ids.
Errors
Section titled “Errors”| Status | error |
When |
|---|---|---|
400 |
invalid_client_order_id |
clientOrderId is empty or longer than 64 characters. |
401 |
unauthorized |
No session, or a missing, expired or revoked token. |
403 |
bearer_required |
by-client-order-id called without a bearer token. |
404 |
not_found |
Unknown id, another credential’s intent, or an account outside your scope. |
States
Section titled “States”state |
Meaning |
|---|---|
intent_pending |
Composed, not yet handed to the matching engine. |
signed_pending_dispatch |
Accepted and about to be dispatched. |
dispatched / acknowledged |
Working: resting on the book. |
partially_filled |
Working, with part of qty executed. |
filled |
Terminal. Fully executed. |
canceled |
Terminal. Canceled by you, by cancel-all, or by the sibling leg of a bracket. |
rejected |
Terminal. Refused after compose. |
replaced |
Terminal. Superseded by a new intent. |
expired |
Terminal. Passed validUntil without being dispatched. |
A terminal state never changes again. The same states arrive on
Order-Intent-Update frames, so a read and the socket always agree on the
vocabulary.