Paper accounts
POST /api/v1/sandbox/paper-account
Provision one
Section titled “Provision one”Every field is optional — an empty body gets sensible defaults.
curl -s https://api.troncharts.xyz/api/v1/sandbox/paper-account \ -H "authorization: Bearer $TOKEN" \ -H "x-tenant-slug: $TC_TENANT_SLUG" \ -H 'content-type: application/json' \ -d '{ "baselineUsd": "50000", "symbol": "BTC.HL", "displayName": "integration rehearsal" }'| Field | Default | Notes |
|---|---|---|
baselineUsd |
"50000" |
Starting balance, as a positive decimal string (0.01 to 1,000,000, at most two decimals). |
symbol |
"BTC.HL" |
The symbol for the demo position. Validated, but no position is opened today — see seedDemoPosition. |
seedDemoPosition |
true |
Accepted for compatibility but currently ignored: no demo position is opened, and the response always says demoPositionSeeded: false. Place your first order yourself. |
displayName |
— | A label for your own bookkeeping. |
issueTraderCredential |
false |
Also issue a trader credential that can place orders on this account. See Trade it. |
The response
Section titled “The response”201, with a fixed shape:
{ "accountId": "…", "accountNumber": "000123", "firmId": "…", "propTenantId": "…", "templateId": "…", "mode": "paper", "demoPositionSeeded": false, "ws": { "hint": "Subscribe on the risk WS …" }}accountId is the canonical identity — use it everywhere. accountNumber is
bare zero-padded digits (a legacy prefixed form is still accepted on input, but
not emitted). firmId and propTenantId carry the same value: the firm
this sandbox account was provisioned under. propTenantId is the older
spelling and reads as a tenant id without being one — prefer firmId.
Who can call it
Section titled “Who can call it”Three gates, checked in this order:
- Deployment — off means
404, before anything else is looked at. - Credential type — an API-client bearer token. A browser cookie
session gets
403 api_client_required. - Tier —
fullTrading.readonlyandliquidationget403 tier_insufficient.
No prop:manage scope is needed. Other failures: 400 invalid_body with the
offending fields, 402 where a card on file is required, and 422 when
provisioning can’t complete.
Read it
Section titled “Read it”The account is in your credential’s ownership scope from the moment it exists:
curl -s https://api.troncharts.xyz/api/v1/accounts \ -H "authorization: Bearer $TOKEN" \ -H "x-tenant-slug: $TC_TENANT_SLUG"
curl -s https://api.troncharts.xyz/api/v1/accounts/$ACCOUNT_ID/state \ -H "authorization: Bearer $TOKEN" \ -H "x-tenant-slug: $TC_TENANT_SLUG"Trade it
Section titled “Trade it”An operator credential provisions paper accounts but cannot place orders on
them: POST /api/v1/oms/intents answers 403 wrong_credential_audience, on
paper as on a real venue (why). Orders come from a
trader credential bound to the account. Ask for one when you provision:
curl -s https://api.troncharts.xyz/api/v1/sandbox/paper-account \ -H "authorization: Bearer $TOKEN" \ -H "x-tenant-slug: $TC_TENANT_SLUG" \ -H 'content-type: application/json' \ -d '{ "seedDemoPosition": false, "issueTraderCredential": true }'The 201 then also carries:
"traderCredential": { "id": "…", "apiKey": "…", "apiSecret": "…", "tier": "fullTrading"}The account and the credential are created together — if one fails, neither
exists. apiSecret is shown only here; store it before you do anything
else. Exchange the pair at POST /api/auth/api-token and use that token for
/api/v1/oms/* on this account. One account per end user means one call per end user.
Stream it
Section titled “Stream it”A /ws/risk socket carries one active account at a time, so after
provisioning you re-subscribe with the new id explicitly:
{ "type": "Subscribe", "id": "…", "topics": ["…"], "accountId": "<accountId>" }The account must be one your credential owns; anything else is rejected with
account_forbidden. You’ll then receive Account-State-Update,
Balance-Update, and Margin-Update for it like any other account — see
Risk channel.
Calling it more than once
Section titled “Calling it more than once”The supporting chain behind a sandbox account is reused across calls, but the
account itself is not deduplicated — every call creates a new one. That’s
deliberate (a clean account per rehearsal), but it means a retry loop around
this endpoint quietly accumulates accounts. Provision once per rehearsal and
keep the accountId.
What the sandbox enforces
Section titled “What the sandbox enforces”The sandbox runs a paper-only template. The template carries two rules:
| Rule | Threshold | At the 50000 default |
|---|---|---|
max_drawdown_usd |
10% of the baseline | 5000 |
daily_loss_cap_usd |
5% of the baseline | 2500 |
Orders are not checked against these rules when they are placed. The risk
engine connected to your instance monitors them, exactly as it does for a real
prop account, and blocks the account with POST /api/v1/accounts/{id}/block
when one is broken. A blocked account refuses new opening orders with
403 account_suspended. Reduce-only orders still go through, so you can close
what you hold.
To rehearse again from a clean state, provision a fresh account with another
POST /api/v1/sandbox/paper-account.
Each distinct baselineUsd gets its own sandbox template. The first one you
provision with becomes the tenant’s base template; a later call with a
different baseline creates (or reuses) a separate template whose thresholds are
computed from that baseline, so the table above holds for every account.
To see the 403 account_suspended your integration has to handle, deliberately
break a rule on a throwaway account.
This is the same flow described in Where rules are enforced, so the error handling you build here carries over to a real template unchanged.