# Balances stream | API reference | Femtos

> What an address holds on HyperEVM (GET /v1/balances/{address}: every token, USD, totals), pushed on subscribe and in the block that changes it. WebSocket channel balances on Elysium and HyperEVM: parameters, response fields and a live call per layer.

- Base URL: `https://api.femtos.xyz/v1` (REST) · `wss://api.femtos.xyz/v1/ws` (WebSocket) · MCP: `https://api.femtos.xyz/mcp`
- Auth: `Authorization: Bearer $FEMTOS_KEY`. Free key: https://dashboard.femtos.xyz/signup (browser), or with
  no browser: `GET https://femtos.xyz/accounts/agent/challenge`, solve its proof of work, then `POST https://femtos.xyz/accounts/agent/signup`
  (https://femtos.xyz/agents.md#agent-onboarding)
- Decimals are exact strings, times Unix milliseconds, addresses lowercase `0x`
- Whole API in one file: https://femtos.xyz/agents.md · OpenAPI: https://api.femtos.xyz/v1/openapi.json · Index: https://femtos.xyz/llms.txt
- Page with live calls: https://femtos.xyz/reference/ws/balances

WebSocket: get a ticket (`POST https://api.femtos.xyz/v1/ws-ticket` with your key), connect to `wss://api.femtos.xyz/v1/ws?ticket=$TICKET`, send the frame below; the first message has `"snapshot": true`. Details: https://femtos.xyz/agents.md#websocket

## Balances stream — WS `balances`

- Elysium: What an address holds on Elysium (GET /v1/balances/{address}: every token, USD, totals), pushed on subscribe and in the block that changes it.
- HyperEVM: What an address holds on HyperEVM (GET /v1/balances/{address}: every token, USD, totals), pushed on subscribe and in the block that changes it.

Layers: Elysium, HyperEVM. Not on HyperCore: a HyperCore account’s balances move with its fills, transfers and funding: the wallet channel streams those (hc.trades, hc.ledger), GET /v1/balances/{address}?layer=hypercore reads them live from our node.
Page with live calls: https://femtos.xyz/reference/ws/balances?layer=<elysium|hyperevm>

| Param | In | Example or values | Meaning |
|---|---|---|---|
| `address` | filter | `0x876f1301aaa8452ceb98201cd4407fa9510a8181` (Elysium); `0x1b86c68e4003a8e139d71a9f06a1b1cc18678626` (HyperEVM) | The address: 0x, or a named wallet's handle |
| `layer` | filter | `elysium` (Elysium); `hyperevm` (HyperEVM) | hyperevm or elysium |
| `tokens` | filter | (optional) | Comma list of token addresses (`native` = HYPE): only those, held or not (0) |
| `minUsd` | filter | (optional) | Leave out holdings worth less (and unpriced ones) |
| `includeSpam` | filter | (optional) | true: also spam tokens (flagged spam), never in the totals |
| `limit` | filter | (optional) | Rows, largest first, default 100 (1..1000) |

Elysium:

```json
{"op":"subscribe","channel":"balances","filter":{"address":"0x876f1301aaa8452ceb98201cd4407fa9510a8181","layer":"elysium"}}
```

HyperEVM:

```json
{"op":"subscribe","channel":"balances","filter":{"address":"0x1b86c68e4003a8e139d71a9f06a1b1cc18678626","layer":"hyperevm"}}
```

| Field | Type | Meaning |
|---|---|---|
| `snapshot: true` | object | the full GET /v1/balances/{address} answer: the first frame, and any frame sent whole |
| `patch: true` | JsonPatch | with "patch": true on subscribe: the operations, in order, that turn the previous answer into this one |
| `billing` | rest | the snapshot a subscribe asks for counts as GET /v1/balances/{address} (rest); every other frame by its bytes (1 credit per 48 KiB) |

## Related (Balances)

- [Balances](https://femtos.xyz/reference/balances.md) `GET /v1/balances/{address}`: Every token an address holds on HyperCore, with USD value and the block it is read at. (Elysium, HyperCore, HyperEVM)
- [Token balance](https://femtos.xyz/reference/token-balance.md) `GET /v1/balances/{address}/{token}`: One token of one address on HyperCore: 0 when not held, now or at a past block. (Elysium, HyperCore, HyperEVM)
- [Batch balances](https://femtos.xyz/reference/batch-balances.md) `POST /v1/balances/batch`: Up to 100 addresses on HyperCore in one call, the same answer for each. (Elysium, HyperCore, HyperEVM)
- [Balances, all layers](https://femtos.xyz/reference/balances-all.md) `GET /v1/balances/{address}`: One address on HyperCore, HyperEVM and Elysium in one list, with totals per layer. (Elysium, HyperCore, HyperEVM)

Every page: https://femtos.xyz/reference.md