Skip to content

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.

  1. POST /api/v1/sandbox/paper-account. Every field is optional and {} is a valid body — the defaults are baselineUsd "50000" and symbol "BTC.HL". seedDemoPosition is accepted but currently ignored: no demo position is opened. The credential must be an API-client credential with tier fullTrading; this route compares the tier for exact equality. A newly minted API client defaults to readonly (tier is optional on POST /api/v1/api-clients), so mint with "tier": "fullTrading" if you will provision or trade. No prop:manage scope is involved.

    Add "issueTraderCredential": true to get a trader credential for the new account back in the same call (see step 3). That flag needs an operator credential; a trader credential can provision an account but not issue one.

    Status error Meaning
    403 api_client_required The bearer is not an API-client token.
    403 tier_insufficient The credential is not fullTrading (readonly and liquidation both fail).
    403 wrong_credential_audience issueTraderCredential was sent by a non-operator credential.
    402 card_required A card is required on this tenant before it can provision.
    422 varies, with detail The account could not be provisioned. Read detail.
    400 invalid_body A field has the wrong type or shape; detail lists 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 } }

    traderCredential is 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/accounts and you can address it by accountId from here on. Field-by-field detail lives on Paper accounts.

  2. The account is funded the moment the 201 lands, and holds no position until you place an order. /state returns balance and equity per venue; /positions returns 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, … } ] }
  3. Mint a bearer token from the traderCredential the 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 sandbox accountId in the OMS body. It is optional on POST /api/v1/oms/intents and defaults to the account the credential is bound to; naming it keeps the call explicit. Use "venue": "paper"; any other venue is 403 live_accounts_disabled; an accountId the credential cannot act on is 403 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