> 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/wallet-activity/wallet-holdings.md).
# Wallet Holdings
Returns a tracked wallet's CURRENT on-chain token balances — the tokens the wallet actually holds right now, read live from the blockchain. This is period-independent: it always reflects the present state, regardless of any time window. Tokens that were fully sold no longer appear (their on-chain balance is zero). Quantities only — no USD or native values.
## Get a wallet's current on-chain holdings
> Returns the wallet's current token balances, sorted by quantity with the chain's native coin (SOL / ETH / BNB) pinned first. Spam tokens and clearly irrelevant dust are filtered out; a maximum of 100 tokens is returned.\
> \
> \*\*Why this is a separate endpoint\*\* — holdings are read live from the blockchain via an on-chain data provider. The first lookup for a wallet can take a few seconds, so it is kept out of the fast \`GET /v1/wallet/tracking\` response. Results are cached per wallet and refreshed at most once every 10 minutes, so repeat calls within that window return instantly.\
> \
> \*\*Recommended usage\*\* — call \`GET /v1/wallet/tracking\` first to render the trading profile immediately, then call this endpoint separately (e.g. when the user opens the "Holdings" tab) to load the balances. If the cache is still warming up, the response returns \`loading: true\` with an empty \`tokens\` array — simply call again a second or two later to get the populated result.\
> \
> \*\*Parameters\*\*\
> \- \`blockchain\` (required) — one of: \`solana\`, \`bnb\`, \`base\`, \`eth\`\
> \- \`address\` (required) — wallet address (Solana base58 or \`0x…\` for EVM chains)\
> \- \`api\_key\` (optional if Bearer header is used)
```json
{"openapi":"3.0.3","info":{"title":"CabalSpy API — Wallet Holdings","version":"1.0.0"},"tags":[{"name":"Wallet Holdings","description":"Returns a tracked wallet's CURRENT on-chain token balances — the tokens the wallet actually holds right now, read live from the blockchain. This is period-independent: it always reflects the present state, regardless of any time window. Tokens that were fully sold no longer appear (their on-chain balance is zero). Quantities only — no USD or native values.\n"}],"servers":[{"url":"https://api.cabalspy.xyz"}],"security":[{"bearerAuth":[]},{"apiKeyQuery":[]}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"Authorization: Bearer YOUR_KEY"},"apiKeyQuery":{"type":"apiKey","in":"query","name":"api_key"}},"schemas":{"WalletHoldingsEnvelope":{"type":"object","properties":{"success":{"type":"boolean"},"data":{"type":"object","properties":{"active_holdings":{"type":"object","description":"Current on-chain token balances. Quantities only — no USD or native values.\n","properties":{"tokens":{"type":"array","items":{"$ref":"#/components/schemas/HoldingToken"}},"count":{"type":"integer","description":"Number of tokens currently held (after filtering)."},"last_updated":{"type":"integer","nullable":true,"description":"Unix timestamp of the last successful refresh (null if never fetched yet)."},"stale":{"type":"boolean","description":"True if these are cached results served after a failed refresh."},"loading":{"type":"boolean","description":"True if the cache is still warming up and no data is available yet. Call the endpoint again a second or two later.\n"}}}}},"meta":{"type":"object"}}},"HoldingToken":{"type":"object","description":"A single currently-held token. Identical field set for all chains (Solana / BNB / Base / ETH). The chain's native coin (SOL / ETH / BNB) uses the pseudo address \"native\". No USD or native value is included.\n","properties":{"token_address":{"type":"string","description":"Contract address (EVM) or mint address (Solana); \"native\" for the chain's native coin."},"token_name":{"type":"string"},"symbol":{"type":"string"},"amount":{"type":"string","description":"Raw balance (smallest unit, not divided by decimals)."},"amount_formatted":{"type":"string","description":"Human-readable balance (raw / 10^decimals)."},"decimals":{"type":"integer"},"verified_contract":{"type":"boolean"},"possible_spam":{"type":"boolean"}}},"ErrorEnvelope":{"type":"object","properties":{"success":{"type":"boolean"},"error":{"type":"object","properties":{"code":{"type":"string"},"message":{"type":"string"},"request_id":{"type":"string"},"docs":{"type":"string"}}}}}}},"paths":{"/v1/wallet/holdings":{"get":{"tags":["Wallet Holdings"],"summary":"Get a wallet's current on-chain holdings","operationId":"getWalletHoldings","description":"Returns the wallet's current token balances, sorted by quantity with the chain's native coin (SOL / ETH / BNB) pinned first. Spam tokens and clearly irrelevant dust are filtered out; a maximum of 100 tokens is returned.\n\n**Why this is a separate endpoint** — holdings are read live from the blockchain via an on-chain data provider. The first lookup for a wallet can take a few seconds, so it is kept out of the fast `GET /v1/wallet/tracking` response. Results are cached per wallet and refreshed at most once every 10 minutes, so repeat calls within that window return instantly.\n\n**Recommended usage** — call `GET /v1/wallet/tracking` first to render the trading profile immediately, then call this endpoint separately (e.g. when the user opens the \"Holdings\" tab) to load the balances. If the cache is still warming up, the response returns `loading: true` with an empty `tokens` array — simply call again a second or two later to get the populated result.\n\n**Parameters**\n- `blockchain` (required) — one of: `solana`, `bnb`, `base`, `eth`\n- `address` (required) — wallet address (Solana base58 or `0x…` for EVM chains)\n- `api_key` (optional if Bearer header is used)\n","parameters":[{"name":"blockchain","in":"query","required":true,"schema":{"type":"string","enum":["solana","bnb","base","eth"]}},{"name":"address","in":"query","required":true,"schema":{"type":"string"}},{"name":"api_key","in":"query","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"Holdings returned. If the cache is still warming up, `loading` is `true` and `tokens` is empty — call again shortly.\n","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WalletHoldingsEnvelope"}}}},"400":{"description":"Missing or invalid parameter.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"401":{"description":"Missing API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"403":{"description":"Invalid or exhausted API key.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"404":{"description":"Wallet not tracked on this chain.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}},"429":{"description":"Rate limit exceeded.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorEnvelope"}}}}}}}}}
```
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter:
```
GET https://cabalspy.gitbook.io/cabalspy-docs/wallet-activity/wallet-holdings.md?ask=
```
The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.