Skip to content

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.

GET /api/v1/oms/intents/{intentId}

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

GET /api/v1/oms/intents

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

GET /api/v1/oms/intents/by-client-order-id/{clientOrderId}

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

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/accounts lists — 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.

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