Trader vs operator credentials
Two very different integrations use this API, and they need different credentials:
- a trader — a person or bot acting on their own account: placing orders, reading their positions, streaming their fills;
- an operator (partner / tenant) — a business acting on its tenant: creating traders, prop firms, challenge templates, risk profiles and trading groups, approving payouts.
A credential is minted for exactly one of these. The audience is fixed at mint and never changes, and one credential can never be both.
What each can do
Section titled “What each can do”| Trader credential | Operator credential | |
|---|---|---|
| Acts on | Its own account | Your tenant |
| Minted from | Paper account: the workspace operator, in the admin console — Account → API keys — or by API with issueTraderCredential on POST /api/v1/accounts/create-prop or POST /api/v1/sandbox/paper-account. Self-minting from a live account is in development |
The admin console — API Clients |
| Carries | A tier (readonly / liquidation / fullTrading), a risk envelope, and venue + symbol allowlists |
Scopes: prop:manage, firm:operate, tenant:config |
| Can place orders | Yes | No — not on a real venue, and not on paper |
| Can administer a tenant | No — scopes are rejected at mint | Yes, and only its own tenant |
Why an operator can’t trade
Section titled “Why an operator can’t trade”Not a missing feature, and not something to work around. Authority over an account comes from that account, never from a credential: only a trader credential is bound to the account it trades.
Sending an operator credential to POST /api/v1/oms/intents with
venue: "paper" is refused with 403 account_not_owned. To trade the
paper accounts you provision, ask for one in the same call:
POST /api/v1/accounts/create-prop (an
account for one of your customers) or
POST /api/v1/sandbox/paper-account (a test
account) with "issueTraderCredential": true returns a fullTrading trader
credential for the new account. The operator credential keeps provisioning; the trader
credential places the orders.
In the SDK
Section titled “In the SDK”Use the client that matches your credential. Calling the other surface then fails at compile time instead of at runtime.
import { TronChartsTrader, TronChartsOperator } from '@tronchartsxyz/api-client'
// Acting on your own accountconst trader = new TronChartsTrader({ baseUrl, token: traderToken, tenantSlug })await trader.oms.place({ /* … */ })await trader.accounts.state(accountId)
// Administering your tenantconst ops = new TronChartsOperator({ baseUrl, token: operatorToken, tenantSlug })const { user } = await ops.users.create({ externalId: 'crm-4471' })await ops.propTemplates.create({ /* … */ })| Client | Resources |
|---|---|
TronChartsTrader |
auth · oms · accounts · propAccounts · market · reports · venues · kyc · referrals · analytics · indicators · backtests · copyTrading |
TronChartsOperator |
auth · users · firms · propTemplates · propSetup · riskProfiles · tradingGroups · tenant · sandbox · propAccounts · reports · analytics |
TronCharts still exposes both surfaces on one object. It works, and it tells
you nothing about which half your token can reach — prefer the scoped clients.
The observer audience
Section titled “The observer audience”A third audience, observer, is a read-only feed of a whole tenant’s account
events for a risk system. Only a platform super admin can create one, in the
admin console (any other admin gets 403 observer_requires_super).
- It never places orders:
POST /api/v1/oms/intentsanswers403 { "error": "observer_credential" }. - It cannot mint credentials:
POST /api/v1/api-clientsanswers403 { "error": "observer_cannot_mint" }. - On
/ws/riskit sees the tenant’s accounts, and a deployment may configure topics that an observer’sSubscribeignores.
If you are integrating as a trader or an operator you will never hold one.
When you get it wrong
Section titled “When you get it wrong”{ "error": "wrong_credential_audience", "detail": "this endpoint is for operator credentials, but this is a trader credential. …", "expected": "operator", "actual": "trader"}HTTP 403. The fix is never to change the credential you have — audiences are
immutable — but to mint the other one and keep both.
You may still meet the older, less direct errors underneath this gate:
| Error | What it actually means |
|---|---|
wrong_credential_audience |
Wrong kind of credential. Mint the other one. |
tier_insufficient |
The credential’s tier is below what the route needs. readonly cannot open or close; liquidation can cancel and flatten but not open; fullTrading can do both. |
prop_manage_required / firm_operate_required / tenant_config_required |
Right audience, missing that specific scope. Scopes are granted per credential and are opt-in at mint, so a credential minted with every box unticked holds none. |
forbidden on reports |
Right credential, wrong account — see the scoping note above. |
Browser sessions
Section titled “Browser sessions”A cookie session (your own logged-in user in the FE) carries no credential and no audience, so this gate does not apply to it. Each route handles it on its own terms: the operator surface refuses it outright — tenant administration is an explicit, audited credential capability — while the trading surface accepts it as the trader it represents.
Next: Credentials & tokens · Scopes & tiers · How an account is configured