GET /balances

GET https://api.trustware.io/api/v1/data/balances/:address Returns token holdings for a wallet address across every chain compatible with that address format, scanned in parallel. Use this to populate an asset selector. The response includes token symbol, balance, decimals, USD price, and logo URI for each holding. The scan covers every compatible chain, so a buffered response waits for the slowest one. Ask for a streamed response to render each chain as it lands instead. Either way, check the partial flag: if true, at least one chain failed or timed out, and the holdings you received are incomplete. An empty wallet and an unreachable chain look identical in the rows themselves, so read partial before you render “no balances”.

Path parameters

Parameter	Description
`address`	The wallet address to scan. The format determines which chains return results: EVM `0x...`, Solana base58, Cosmos bech32 (`sei1...`, `nibi1...`), or Bitcoin bech32. The endpoint validates the address against each chain it scans.

Query parameters

Parameter	Description
`stream`	Set to `1` (or `true`) to stream per-chain results as newline-delimited JSON instead of buffering them. Omit it, or pass `0`, for the buffered response.
`format`	Set to `ndjson` for the same streamed response. Equivalent to `stream=1`. A `stream` value that parses as a boolean takes precedence over `format`.

Response

{
  "address": "0xeb212fe20f26243ec4d4df2dd49c8aa9fa75a201",
  "partial": true,
  "results": [
    {
      "chain_id": "1329",
      "source": "alchemy",
      "balances": [
        {
          "chain_key": "1329",
          "category": "native",
          "symbol": "SEI",
          "decimals": 18,
          "balance": "0"
        }
      ],
      "count": 1,
      "error": null
    },
    {
      "chain_id": "25",
      "source": "fallback",
      "balances": [
        {
          "chain_key": "25",
          "category": "native",
          "symbol": "CRO",
          "decimals": 18,
          "balance": "0"
        }
      ],
      "count": 1,
      "error": null
    }
  ]
}

Response fields

Field	Description
`address`	The queried wallet address.
`partial`	`true` if at least one chain returned an error or timed out, so the holdings are incomplete.
`results`	Array of per-chain balance objects.
`results[].chain_id`	Chain ID for this result set.
`results[].source`	Data source used for this chain (`alchemy`, `fallback`, etc.).
`results[].balances`	Array of token balances on this chain.
`results[].count`	Number of tokens returned for this chain.
`results[].error`	Error message if balance fetching failed for this chain, otherwise `null`.

Balance object fields

Field	Description
`chain_key`	Chain identifier (matches `chain_id` for EVM chains; may be a string key for non-EVM).
`category`	Token category: `native`, `erc20`, `spl`, `btc`, or `bank`. Cosmos balances are tagged `bank`, including the chain’s native token.
`contract`	Token contract address (for ERC-20 and SPL tokens).
`symbol`	Token ticker symbol.
`decimals`	Token decimal places. Divide `balance` by `10^decimals` for a human-readable amount.
`balance`	Raw balance in the smallest unit of the token.
`name`	Full token name.
`logoURI`	Token logo image URL.
`usdPrice`	Current USD price per token.

Streaming responses

Pass ?stream=1 (or ?format=ndjson) to receive each chain’s result as soon as that chain answers, rather than waiting for the whole scan. The endpoint responds with 200 OK and streams newline-delimited JSON: one JSON object per line, terminated by a summary line.

curl -N "https://api.trustware.io/api/v1/data/balances/0xeb212fe20f26243ec4d4df2dd49c8aa9fa75a201?stream=1" \
  -H "X-API-Key: $TW_KEY" \
  -H "Accept: application/x-ndjson"

The streamed response carries these headers. X-Accel-Buffering: no is there to stop an intermediate proxy from buffering the body and erasing the benefit, so preserve it if you proxy this endpoint yourself.

Content-Type: application/x-ndjson
Cache-Control: no-cache
X-Accel-Buffering: no

Frames

{"type":"chain_result","chainIndex":3,"completed":1,"total":42,"lastCompletedChain":"8453","chain_id":"8453","source":"alchemy","balances":[{"chain_key":"8453","category":"native","symbol":"ETH","decimals":18,"balance":"41230000000000000"}],"count":1,"error":null}
{"type":"chain_result","chainIndex":0,"completed":2,"total":42,"lastCompletedChain":"1","chain_id":"1","source":"alchemy","balances":[],"count":0,"error":null}
{"type":"summary","address":"0xeb212fe20f26243ec4d4df2dd49c8aa9fa75a201","partial":false,"completed":42,"total":42,"elapsed":2310}

Read type to tell the two frames apart. A chain_result frame carries the same per-chain object the buffered results[] array holds, flattened to the top level and wrapped with progress counters.

Field	Description
`type`	`"chain_result"`.
`chainIndex`	Position of this chain in the server’s scan list. This is the same ordering the buffered `results[]` array uses, so it is stable within one scan.
`completed`	Number of chains that have reported so far, including this one.
`total`	Number of chains in this scan. Constant across every frame.
`lastCompletedChain`	Chain ID this frame reports. Same value as `chain_id`.
`chain_id`	Chain ID for this result set.
`source`	Data source used for this chain (`alchemy`, `fallback`, etc.).
`balances`	Array of token balances on this chain, in the balance object shape.
`count`	Number of tokens returned for this chain.
`error`	Error message if balance fetching failed for this chain, otherwise `null`.

The summary frame closes the stream.

Field	Description
`type`	`"summary"`.
`address`	The queried wallet address.
`partial`	`true` if any chain reported an error during the scan.
`completed`	Chains that reported a result. A chain that errored still reports, so this equals `total` on an ordinary partial scan. Read `partial`, not this, to tell whether the scan was complete.
`total`	Number of chains in this scan.
`elapsed`	Server-side scan duration in milliseconds.

Consuming the stream

Frames arrive in completion order, not in chain order, so a fast chain reports ahead of a slow one. Merge each frame into your own map keyed by chain_id rather than appending, and drive any progress indicator off completed and total.

The 200 OK is sent before the scan starts, so a mid-stream failure cannot change the status code. It shows up as a truncated body with no summary frame. Treat a stream that ends without a summary as partial: true.

Streaming is enabled per deployment. Where it is off, the endpoint rejects the request rather than silently buffering:

{
  "error": "stream mode disabled",
  "request_id": "5f8c2f0e-..."
}

That response is a 400, so treat it as a signal to retry the same URL without stream, not as a scan failure. Check the response Content-Type before you parse: a deployment that answers application/json to a streamed request has served you the buffered payload, and reading it line by line will fail.

The React SDK does all of this for you. Trustware.getBalancesByAddressStream streams by default from SDK 1.1.12, reports the summary through onSummary, and falls back to the buffered response (emitting balance_stream_fallback) when streaming is refused or aborted, or the runtime has no readable response body. See BalanceStreamOptions.

Partial responses

When partial: true, some chains responded with an error or did not return data before the scan finished. The results[].error field on each chain entry, or the error field on a streamed chain_result frame, indicates if that chain encountered an issue. Chains with error: null returned successfully.

Getting Started

Endpoints

Path parameters

Query parameters

Response

Response fields

Balance object fields

Streaming responses

Frames

Consuming the stream

Partial responses

​Path parameters

​Query parameters

​Response

​Response fields

​Balance object fields

​Streaming responses

​Frames

​Consuming the stream

​Partial responses

Path parameters

Query parameters

Response

Response fields

Balance object fields

Streaming responses

Frames

Consuming the stream

Partial responses