# 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.

   :::note[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.
   :::

   ```bash
   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, … } ] }
   ```
   ```ts
   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.

   ```bash
   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 } ]
   ```
   ```ts
   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.

   :::caution[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`.
   :::

   ```bash
   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 } ] }
   ```
   ```ts
   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.

   ```bash
   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](https://docs.troncharts.xyz/docs/trading/accounts/) · [Stream account and position updates](https://docs.troncharts.xyz/docs/recipes/stream-account-updates/) · [Create a paper account](https://docs.troncharts.xyz/docs/recipes/create-a-paper-account/)