Read balance, positions and open orders

Everything readable about an account hangs off /api/v1/accounts/{id}/* — what it is worth, what it holds, and what is still working. {id} takes the account UUID or the bare account number (PH-000123, or the digits), and a readonly credential is enough for every call here.

1. Read balance and equity

   GET /accounts/{id}/state returns one row per venue the account has traded on. Amounts are USD decimal strings.

   There is no account total

   /state returns no top-level equityUsd, balanceUsd or buyingPower — the response is { accountId, accountNumber, perVenue } and nothing else. Sum perVenue yourself for an account-wide figure.

   curl

   curl -s https://api.troncharts.xyz/api/v1/accounts/$ACCOUNT_ID/state \
     -H "authorization: Bearer $TOKEN" \
     -H "x-tenant-slug: $TC_TENANT_SLUG"
   # → { accountId, accountNumber,
   #     perVenue: [ { venue, exchange, equityUsd, balanceUsd, marginUsedUsd,
   #                   marginAvailableUsd, unrealizedPnlUsd, source, … } ] }

   TypeScript

   const state = await sdk.accounts.state(accountId)
   const equityUsd = state.perVenue
     .reduce((sum, v) => sum + Number(v.equityUsd), 0)

2. Read open positions

   GET /accounts/{id}/positions returns { accountId, accountNumber, positions }. unrealizedPnlUsd is computed from markPrice and is null whenever the mark is unavailable — treat it as nullable, not zero.

   curl

   curl -s https://api.troncharts.xyz/api/v1/accounts/$ACCOUNT_ID/positions \
     -H "authorization: Bearer $TOKEN" \
     -H "x-tenant-slug: $TC_TENANT_SLUG"
   # → positions: [ { venue, exchange, symbol, side, qty, entryPrice, markPrice,
   #                  liquidationPrice, leverage, unrealizedPnlUsd,
   #                  openedAt, updatedAt } ]

   TypeScript

   const { positions } = await sdk.accounts.positions(accountId)
   const open = positions.filter((p) => Number(p.qty) !== 0)

3. Read orders

   GET /accounts/{id}/orders reads the OMS order intents, so status is the intent state and side comes back long / short, not buy / sell. Filters: venue, symbol, cursor, limit (1–1000, default 100). Page by passing nextCursor back until it is null.

   For orders working at the venue — including any placed outside the OMS — use GET /accounts/{id}/order-history?status=open. It is the only one of the two that reads a status filter; /orders ignores it silently.

   The SDK’s response type is wrong here

   SDK 0.3.0 types accounts.orders and accounts.trades as Page<T>, i.e. { data, nextCursor, hasMore }. The routes return { orders, nextCursor } and { trades, total, nextCursor } — read the named array, never data.

   curl

   curl -s "https://api.troncharts.xyz/api/v1/accounts/$ACCOUNT_ID/orders?limit=50" \
     -H "authorization: Bearer $TOKEN" \
     -H "x-tenant-slug: $TC_TENANT_SLUG"
   # → { accountId, accountNumber, nextCursor,
   #     orders: [ { orderId, venueOrderId, venue, exchange, symbol, side,
   #                 type, status, qty, price, triggerPrice, timeInForce,
   #                 reduceOnly, kind, parentIntentId, composedAt } ] }

   TypeScript

   const page = await sdk.accounts.orders(accountId, { limit: 50 }) as unknown as {
     orders: { orderId: string; venueOrderId: string | null; status: string }[]
     nextCursor: string | null
   }
   console.log(page.orders.length, page.nextCursor)

4. Read closed round-trips

   GET /accounts/{id}/trades aggregates entry and exit into one row per round-trip, with realized P&L and the fee split. sdk.accounts.trades(accountId) is the SDK equivalent, with the caveat from step 3.

   curl -s "https://api.troncharts.xyz/api/v1/accounts/$ACCOUNT_ID/trades?limit=50" \
     -H "authorization: Bearer $TOKEN" \
     -H "x-tenant-slug: $TC_TENANT_SLUG"
   # → { accountId, accountNumber, total, nextCursor,
   #     trades: [ { tradeId, symbol, side, qty, avgEntryPrice, avgClosePrice,
   #                 openTime, closeTime, pnlUsd, pnlPct, durationMs,
   #                 fees: { total, maker, taker } } ] }

Next: Accounts & positions · Stream account and position updates · Create a paper account