Get account balances
Returns current balances for a linked account, identified by its UUID. Each row is one asset wallet and includes cost basis, market value, realized and unrealized gains, and a status for each computed figure.
Endpoint
http
GET /v1/api/account/{accountId}/balancesAuthentication: Bearer token.
Parameters
| Parameter | In | Type | Required | Description |
|---|---|---|---|---|
| accountId | path | string (uuid) | Yes | Unique identifier of the linked account. |
| forceRefresh | query | boolean | No | Refresh from the source instead of the cache. Applies only when the cached data is older than 30 minutes, and is ignored while the account's first sync is still running. Defaults to false. |
Example request
bash
curl -X GET 'https://api.turnqey.xyz/v1/api/account/0f1e2d3c-4b5a-4c6d-8e9f-0a1b2c3d4e5f/balances?forceRefresh=false' \
-H 'accept: application/json' \
-H 'Authorization: Bearer <token>'Example response
json
{
"statusCode": 200,
"message": "GET Request successful.",
"isError": false,
"result": {
"balances": [
{
"walletId": "7c1f4b2e-3d5a-4e6f-9a8b-0c1d2e3f4a5b",
"symbol": "BTC",
"balance": "0.5",
"currentPrice": "50000.00",
"marketValue": "25000.00",
"costBasis": "24500.00",
"realizedGainLoss": "500.00",
"unrealizedGainLoss": "500.00",
"costBasisStatus": "complete",
"realizedGainLossStatus": "complete",
"unrealizedGainLossStatus": "complete"
}
],
"marketValue": "25000.00",
"realizedGainLoss": "500.00",
"unrealizedGainLoss": "500.00",
"lastUpdatedOn": "2026-10-30T14:00:00Z",
"transactionSyncStatus": "complete",
"costBasisStatus": "complete",
"realizedGainLossStatus": "complete",
"unrealizedGainLossStatus": "complete"
}
}Per-row fields
| Field | Type | Description |
|---|---|---|
| walletId | string | Source wallet identifier. The same asset can appear in more than one wallet. Null for Gemini and fiat rows. |
| symbol | string | Asset symbol. |
| balance | string | Asset quantity held. |
| currentPrice | string | Current price per unit. |
| marketValue | string | balance times currentPrice. |
| costBasis | string | Cost basis of the holding. |
| realizedGainLoss | string | Realized gain or loss. |
| unrealizedGainLoss | string | Unrealized gain or loss. |
| costBasisStatus, realizedGainLossStatus, unrealizedGainLossStatus | string | Whether the figure could be fully computed from the available transaction history. |
Top-level fields
| Field | Type | Description |
|---|---|---|
| marketValue, realizedGainLoss, unrealizedGainLoss | string | Totals across all rows. |
| lastUpdatedOn | string (date-time) | When the snapshot was last refreshed from the source. |
| transactionSyncStatus | string | complete, stale, or reconnect_required. |
| costBasisStatus, realizedGainLossStatus, unrealizedGainLossStatus | string | Account-level roll-up of the per-row statuses. |
| dataFreshness | object | Present only when the snapshot is stale: {status, asOf, ageHours, reason}. See Data Freshness. |
Numeric values are returned as strings to preserve precision.
Errors
| Status | Meaning |
|---|---|
| 401 | Bearer token missing, expired, or invalid. |
| 404 | No active connection exists for the supplied accountId. |
| 409 | Reserved: the account must be re-authorized before data can be served. Not enabled in production today; the same condition is signalled through dataFreshness.status. |
| 429 | Rate limit exceeded (300 requests per minute per source IP, per endpoint). Honour Retry-After. |
See Data Freshness for caching and refresh behavior, and Errors and Retries for error handling.