> For the complete documentation index, see [llms.txt](https://cabalspy.gitbook.io/cabalspy-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://cabalspy.gitbook.io/cabalspy-docs/data-stream/balance.md).

# Balance

Live native SOL balances of tracked KOL, smart-money and whale wallets on Solana. Refreshed on every transaction; snapshot on subscribe.

## Balance — Live Native SOL Balances of Tracked Wallets (WebSocket)

> Subscribe and receive an \`init\` snapshot of current balances, then live \`balance\_update\` messages each time a tracked wallet's SOL balance changes.\
> \
> \- \`blockchain\` (required) — must be \`solana\`.\
> \- \`wallet\` (optional, default \`\*\`) — a wallet address to follow one wallet,\
>   or \`\*\` for all tracked wallets.\
> \
> \- \`wallet\_types\` (optional) — any subset of \`kol\`, \`smart\`, \`whale\`;\
> &#x20; defaults to all three.<br>

```json
{"openapi":"3.0.3","info":{"title":"CabalSpy API — Balance Stream (Live Native SOL Balances of Tracked Wallets)","version":"2.0.0"},"tags":[{"name":"Balance","description":"Live native SOL balances of tracked KOL, smart-money and whale wallets on Solana. Refreshed on every transaction; snapshot on subscribe.\n"}],"servers":[{"url":"wss://stream.cabalspy.xyz","description":"Production WebSocket gateway"}],"security":[{"bearerAuth":[]},{"apiKeyQuery":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"Authorization: Bearer YOUR_KEY"},"apiKeyQuery":{"type":"apiKey","in":"query","name":"apiKey"}},"schemas":{"SubscribeBalanceMessage":{"type":"object","description":"Client -> server. Subscribe to tracked wallets' native SOL balances; filters persist until unsubscribe.","properties":{"op":{"type":"string","enum":["subscribe"]},"stream":{"type":"string","enum":["balance"]},"blockchain":{"type":"string","enum":["solana"],"description":"Must be solana."},"wallet":{"type":"string","description":"A wallet address, or \"*\" for all tracked wallets."},"wallet_types":{"type":"array","items":{"type":"string","enum":["kol","smart","whale"]},"description":"Any subset; defaults to all three if omitted."},"channel":{"type":"string","description":"Alternative to blockchain+wallet: balance.solana.<wallet> or balance.solana for all.","nullable":true}},"required":["op","stream"]},"BalanceEnvelope":{"type":"object","description":"One balance message — init snapshot or balance_update.","properties":{"success":{"type":"boolean"},"channel":{"type":"string"},"event":{"type":"string","enum":["init","balance_update"]},"data":{"type":"object","properties":{"blockchain":{"type":"string","enum":["solana"]},"wallet_types":{"type":"array","items":{"type":"string","enum":["kol","smart","whale"]},"nullable":true,"description":"Present on init."},"balances":{"type":"array","nullable":true,"description":"Present on init — current balances of all subscribed wallets.","items":{"$ref":"#/components/schemas/BalanceEntry"}},"wallet":{"type":"string","nullable":true,"description":"Present on balance_update — the wallet whose balance changed."},"profile":{"allOf":[{"$ref":"#/components/schemas/Profile"}],"nullable":true,"description":"Present on balance_update."},"balance":{"allOf":[{"$ref":"#/components/schemas/BalanceValue"}],"nullable":true,"description":"Present on balance_update."}}},"meta":{"type":"object","properties":{"request_id":{"type":"string"},"version":{"type":"string"},"timestamp":{"type":"string","format":"date-time"}}}}},"BalanceEntry":{"type":"object","description":"One wallet with profile and balance (init snapshot).","properties":{"wallet":{"type":"string"},"profile":{"$ref":"#/components/schemas/Profile"},"balance":{"$ref":"#/components/schemas/BalanceValue"}}},"Profile":{"type":"object","description":"Identity and classification of a tracked wallet (no active_hours on this stream).","properties":{"name":{"type":"string"},"image_url":{"type":"string"},"twitter":{"type":"string"},"telegram":{"type":"string"},"blockchain":{"type":"string","enum":["solana"]},"currency":{"type":"string","enum":["SOL"]},"type":{"type":"string","enum":["kol","smart","whale"],"nullable":true}}},"BalanceValue":{"type":"object","description":"A wallet's native SOL balance.","properties":{"currency":{"type":"string","enum":["SOL"]},"amount":{"type":"number","description":"Balance in SOL."},"amount_raw":{"type":"string","description":"Balance in lamports (integer as string)."},"amount_usd":{"type":"number","nullable":true,"description":"amount at the current SOL/USD price."},"decimals":{"type":"integer"},"symbol":{"type":"string"},"name":{"type":"string"},"previous_amount":{"type":"number","nullable":true,"description":"Previous balance in SOL (present on balance_update)."},"previous_amount_raw":{"type":"string","nullable":true,"description":"Previous balance in lamports (present on balance_update)."},"updated_at":{"type":"integer","description":"Unix ms of the balance read."}}}}},"paths":{"/balance":{"get":{"tags":["Balance"],"summary":"Balance — Live Native SOL Balances of Tracked Wallets (WebSocket)","operationId":"streamBalance","description":"Subscribe and receive an `init` snapshot of current balances, then live `balance_update` messages each time a tracked wallet's SOL balance changes.\n\n- `blockchain` (required) — must be `solana`.\n- `wallet` (optional, default `*`) — a wallet address to follow one wallet,\n  or `*` for all tracked wallets.\n\n- `wallet_types` (optional) — any subset of `kol`, `smart`, `whale`;\n  defaults to all three.\n","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubscribeBalanceMessage"}}}},"responses":{"200":{"description":"`init` and `balance_update` messages. (The connection also delivers a `connected` welcome, a `subscribed` ack per subscribe, and `error` messages — see schemas.)\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/BalanceEnvelope"}}}}}}}}}
```