Skip to content

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.

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

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.

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 account
const trader = new TronChartsTrader({ baseUrl, token: traderToken, tenantSlug })
await trader.oms.place({ /* … */ })
await trader.accounts.state(accountId)
// Administering your tenant
const 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.

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/intents answers 403 { "error": "observer_credential" }.
  • It cannot mint credentials: POST /api/v1/api-clients answers 403 { "error": "observer_cannot_mint" }.
  • On /ws/risk it sees the tenant’s accounts, and a deployment may configure topics that an observer’s Subscribe ignores.

If you are integrating as a trader or an operator you will never hold one.

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

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