Quickstart
Three calls, start to finish. You need a credential — { apiKey, apiSecret } —
from self-serve signup or your admin console.
1. Mint a bearer token
Section titled “1. Mint a bearer token”curl -s https://api.troncharts.xyz/api/auth/api-token \ -H 'content-type: application/json' \ -d '{"apiKey":"'"$TC_API_KEY"'","apiSecret":"'"$TC_API_SECRET"'"}'# → { "token": "eyJ…", "tier": "fullTrading", "expiresAt": <epoch ms>, … }The token is a 24-hour JWT. Send it as Authorization: Bearer <token> on every
call below. Revoke early with POST /api/auth/api-token/revoke ({ token }).
You do not need to say which tenant your calls are for. Your credential is
bound to one tenant at mint time, and that binding scopes every /api/v1/* call
— read off your credential server-side, so calling from your own backend or any
unregistered host works. X-Tenant-Slug is not needed on a bearer call (it is
inert there), so the examples omit it. See Tenancy.
2. Read account state
Section titled “2. Read account state”curl -s https://api.troncharts.xyz/api/v1/accounts/$ACCOUNT_ID/state \ -H "authorization: Bearer $TOKEN"# → { accountId, accountNumber,# perVenue: [ { venue, exchange, equityUsd, balanceUsd, marginUsedUsd,# marginAvailableUsd, unrealizedPnlUsd, … } ] }There are no top-level balance or equity fields: every figure is per venue,
USD-denominated, and returned as a decimal string. The account total is the sum
across perVenue.
Everything readable about an account — positions, orders, trades, fills,
funding — hangs off the same /api/v1/accounts/{accountId}/* prefix. See
Accounts & positions.
3. Place an order intent
Section titled “3. Place an order intent”Requires a trader credential with the fullTrading tier (see above).
curl -s https://api.troncharts.xyz/api/v1/oms/intents \ -H "authorization: Bearer $TOKEN" \ -H 'content-type: application/json' \ -H "idempotency-key: $(uuidgen)" \ -d '{ "venue": "paper", "symbol": "BTC.HL", "side": "buy", "type": "market", "qty": "0.01" }'# → 201 { "intentId": "…", "state": "filled",# "syncFill": { "qty": "0.01", "avgPrice": "64210.5" } }An order that stays open (a resting limit, for example) answers 201 with
only { "intentId": "…" } — no state, no syncFill. Follow it over
/ws/risk or read it back by intentId.
Every account trades paper today, so venue is always "paper" — any other
venue answers 403 {"error":"live_accounts_disabled"}. See
Paper-only mode.
One endpoint covers market / limit / stop / stop_limit /
take_profit. An order is an intent: a marketable paper order fills
synchronously and the 201 already carries the fill; everything that happens
to it afterwards (working, filled, canceled) arrives over
/ws/risk rather than by polling.
accountId is optional — omit it and the credential’s active account is used.
Always send an idempotency-key on OMS writes — /api/v1/oms/* is the surface
that honours it; see Conventions.
The same three steps in TypeScript
Section titled “The same three steps in TypeScript”The client is constructed with a token — there is no anonymous client, so
mint the token first with a plain fetch. tenantSlug is optional — pass it and
the SDK sends X-Tenant-Slug on every request, but your credential already
carries the tenant that scopes the call.
import { TronCharts } from '@tronchartsxyz/api-client'
const res = await fetch('https://api.troncharts.xyz/api/auth/api-token', { method: 'POST', headers: { 'content-type': 'application/json' }, body: JSON.stringify({ apiKey, apiSecret }),})const { token } = (await res.json()) as { token: string }
const sdk = new TronCharts({ baseUrl: 'https://api.troncharts.xyz', token, tenantSlug: 'your-slug',})
const state = await sdk.accounts.state(accountId)const { intentId } = await sdk.oms.composeIntent({ venue: 'paper', symbol: 'BTC.HL', side: 'buy', type: 'market', qty: '0.01',})- Paper-only mode — what works on paper and what to call instead.
- Base URLs & discovery — never hardcode a venue list.
- Scopes & tiers — what your credential is allowed to do.
- Connecting — stream state instead of polling.