Create a paper account to test against
One call provisions a paper account with a starting balance, so your first reads return real data and your first orders run the real pipeline without real money.
-
Provision the account
Section titled “Provision the account”POST /api/v1/sandbox/paper-account. Every field is optional and{}is a valid body — the defaults arebaselineUsd"50000"andsymbol"BTC.HL".seedDemoPositionis accepted but currently ignored: no demo position is opened. The credential must be an API-client credential with tierfullTrading; this route compares the tier for exact equality. A newly minted API client defaults toreadonly(tieris optional onPOST /api/v1/api-clients), so mint with"tier": "fullTrading"if you will provision or trade. Noprop:managescope is involved.Add
"issueTraderCredential": trueto get a trader credential for the new account back in the same call (see step 3). That flag needs anoperatorcredential; a trader credential can provision an account but not issue one.Status errorMeaning 403api_client_requiredThe bearer is not an API-client token. 403tier_insufficientThe credential is not fullTrading(readonlyandliquidationboth fail).403wrong_credential_audienceissueTraderCredentialwas sent by a non-operator credential.402card_requiredA card is required on this tenant before it can provision. 422varies, with detailThe account could not be provisioned. Read detail.400invalid_bodyA field has the wrong type or shape; detaillists each issue.Terminal window curl -s https://api.troncharts.xyz/api/v1/sandbox/paper-account \-H "authorization: Bearer $TOKEN" \-H 'content-type: application/json' \-d '{"baselineUsd":"50000","symbol":"BTC.HL","displayName":"integration rehearsal","issueTraderCredential":true}'# → 201 { accountId, accountNumber, firmId, propTenantId, templateId,# mode: "paper", demoPositionSeeded: false,# traderCredential: { id, apiKey, apiSecret, tier }, ws: { hint } }const sandbox = await sdk.sandbox.paperAccount({baselineUsd: '50000',symbol: 'BTC.HL',displayName: 'integration rehearsal',})const accountId = sandbox.accountIdtraderCredentialis present only when you asked for it. Store the secret now: it is the credential that can trade this account.The new account is linked into the calling credential’s ownership scope, so it shows up in
GET /api/v1/accountsand you can address it byaccountIdfrom here on. Field-by-field detail lives on Paper accounts. -
Read the funded state back
Section titled “Read the funded state back”The account is funded the moment the 201 lands, and holds no position until you place an order.
/statereturns balance and equity per venue;/positionsreturns what it holds.Terminal window 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, … } ] }const state = await sdk.accounts.state(accountId)const { positions } = await sdk.accounts.positions(accountId)console.log(state.perVenue, positions.length) -
Point your order flow at it
Section titled “Point your order flow at it”Mint a bearer token from the
traderCredentialthe call returned (POST /api/auth/api-token) and place orders with that token: operator and observer credentials cannot place orders (see Trader vs operator credentials). Send the sandboxaccountIdin the OMS body. It is optional onPOST /api/v1/oms/intentsand defaults to the account the credential is bound to; naming it keeps the call explicit. Use"venue": "paper"; any other venue is403 live_accounts_disabled; anaccountIdthe credential cannot act on is403 account_not_owned.Terminal window curl -s https://api.troncharts.xyz/api/v1/oms/intents \-H "authorization: Bearer $TRADER_TOKEN" \-H 'content-type: application/json' \-H "idempotency-key: $(uuidgen)" \-d '{"accountId":"'"$ACCOUNT_ID"'","venue":"paper","symbol":"BTC.HL","side":"buy","type":"market","qty":"0.01"}'The paper engine matches synchronously, so a market order comes back as
201 { intentId, state: "filled", syncFill: { qty, avgPrice } }. The full body schema is on Orders & OMS.
Next: Place your first order · Read balance, positions and open orders · Stream account updates