> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cabalspy.xyz/llms.txt
> Use this file to discover all available pages before exploring further.

# Holdings

> GET /v1/wallets/holdings: current token balances of a verified wallet with USD value, read from the chain.

The current token balances of a verified wallet of your users, with price and USD value, read from the chain. Balances worth less than \$0.01 are hidden. Tokens are sorted by USD value, largest first.

Use it to show a portfolio on a profile page or to check what a trader you copy is holding right now.

<Tip>
  Holdings are cached for 30 seconds. meta.cached and meta.cache\_age\_seconds show the age of the data.
</Tip>

## Query Parameters

<ParamField query="blockchain" type="string" required>
  Chain of the wallet. One of solana, bnb, base, eth, rh.
</ParamField>

<ParamField query="address" type="string" required>
  A wallet verified on this chain by one of your users.
</ParamField>

<ParamField query="scope" default="instance" type="string">
  `global` allows any CabalSpy ID wallet. Enterprise plan only.
</ParamField>

<ParamField query="instance" type="string">
  Your Instance ID. Only needed when your account has several instances.
</ParamField>

<ParamField query="api_key" type="string" required>
  Your API key. Alternatively pass it as an Authorization Bearer header.
</ParamField>

## Usage Example

<CodeGroup>
  ```bash cURL theme={null}
  curl "https://api-id.cabalspy.xyz/v1/wallets/holdings?blockchain=solana&address=7j7AA3HZR2zEjwAQEKPFh2qucLY4fqZpB9iodf39w8xW" \
    -H "Authorization: Bearer YOUR_KEY"
  ```

  ```python Python theme={null}
  import requests

  params = {"blockchain": "solana", "address": "7j7AA3HZR2zEjwAQEKPFh2qucLY4fqZpB9iodf39w8xW"}
  r = requests.get("https://api-id.cabalspy.xyz/v1/wallets/holdings", params=params,
                   headers={"Authorization": "Bearer YOUR_KEY"})
  h = r.json()["data"]["active_holdings"]
  print(h["count"], "tokens worth", h["total_value_usd"], "USD")
  for t in h["tokens"][:5]:
      print(t["symbol"], t["amount_formatted"], t["value_usd"])
  ```

  ```javascript JavaScript theme={null}
  const p = new URLSearchParams({
    blockchain: "solana",
    address: "7j7AA3HZR2zEjwAQEKPFh2qucLY4fqZpB9iodf39w8xW",
  });
  const res = await fetch(`https://api-id.cabalspy.xyz/v1/wallets/holdings?${p}`, {
    headers: { Authorization: "Bearer YOUR_KEY" },
  });
  const { data } = await res.json();
  console.log(data.active_holdings.total_value_usd, data.active_holdings.tokens);
  ```
</CodeGroup>

## Response

<ResponseField name="success" type="boolean">
  True on success.
</ResponseField>

<ResponseField name="data" type="object">
  <Expandable title="data">
    <ResponseField name="wallet" type="string">
      The wallet address.
    </ResponseField>

    <ResponseField name="blockchain" type="string">
      Chain.
    </ResponseField>

    <ResponseField name="profile" type="object">
      The owner's profile, the same fields as on the [tracker](/cabalspy-id/tracker).
    </ResponseField>

    <ResponseField name="active_holdings" type="object">
      <Expandable title="active_holdings">
        <ResponseField name="tokens" type="array">
          <Expandable title="token">
            <ResponseField name="token_address" type="string">
              Token mint or contract.
            </ResponseField>

            <ResponseField name="token_name" type="string">
              Token name.
            </ResponseField>

            <ResponseField name="symbol" type="string">
              Token symbol.
            </ResponseField>

            <ResponseField name="logo" type="string">
              Token logo URL.
            </ResponseField>

            <ResponseField name="amount" type="string">
              Raw balance in the token's smallest unit.
            </ResponseField>

            <ResponseField name="amount_formatted" type="string">
              Balance in whole tokens.
            </ResponseField>

            <ResponseField name="decimals" type="integer">
              Token decimals.
            </ResponseField>

            <ResponseField name="price_usd" type="number">
              Token price in USD.
            </ResponseField>

            <ResponseField name="value_usd" type="number">
              Value of the balance in USD.
            </ResponseField>

            <ResponseField name="verified_contract" type="boolean">
              Reserved, currently null.
            </ResponseField>
          </Expandable>
        </ResponseField>

        <ResponseField name="count" type="integer">
          Number of tokens.
        </ResponseField>

        <ResponseField name="total_value_usd" type="number">
          Total value of all tokens in USD.
        </ResponseField>

        <ResponseField name="last_updated" type="string">
          When the balances were read.
        </ResponseField>

        <ResponseField name="stale" type="boolean">
          True when the cached balances are older than 30 seconds.
        </ResponseField>

        <ResponseField name="loading" type="boolean">
          Always false, kept for compatibility with the CabalSpy API.
        </ResponseField>
      </Expandable>
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseExample>
  ```json Response theme={null}
  {
    "success": true,
    "data": {
      "wallet": "7j7AA3HZR2zEjwAQEKPFh2qucLY4fqZpB9iodf39w8xW",
      "blockchain": "solana",
      "profile": {
        "csid_id": "0b7c4a52-3f1e-4f43-9d0a-2b5e7c1d9a11",
        "username": "MazeCCC",
        "name": "Maze",
        "image_url": "https://pbs.twimg.com/profile_images/.../photo.jpg",
        "twitter": "https://x.com/MazeCCC",
        "telegram": "",
        "blockchain": "solana",
        "currency": "SOL",
        "type": "csid",
        "kol": true,
        "active_hours": "",
        "profile_url": "https://id.cabalspy.xyz/u/MazeCCC"
      },
      "active_holdings": {
        "tokens": [
          {
            "token_address": "3Pkrq4MmLvDXyn1fa3sz5MekKRkZkc1iLDcz5AzWpump",
            "token_name": "invisibull",
            "symbol": "invisibull",
            "logo": "https://...",
            "amount": "22113972030000",
            "amount_formatted": "22113972.03",
            "decimals": 6,
            "price_usd": 0.0000071,
            "value_usd": 157.009201,
            "verified_contract": null
          }
        ],
        "count": 1,
        "total_value_usd": 157.01,
        "last_updated": "2026-10-13T08:04:11Z",
        "stale": false,
        "loading": false
      }
    },
    "meta": {
      "request_id": "req_5162c7cf7f87",
      "cached": false,
      "cache_age_seconds": 0,
      "version": "v1",
      "timestamp": "2026-10-13T08:04:11Z"
    }
  }
  ```
</ResponseExample>

## Errors

| Status | Code | Meaning |
| - | - | - |
| 400 | missing\_parameter | blockchain or address is missing. |
| 400 | invalid\_parameter | blockchain or address invalid. |
| 401 | missing\_api\_key | API key missing. |
| 403 | invalid\_api\_key | API key invalid or not enabled for CabalSpy ID. |
| 403 | scope\_not\_allowed | scope=global needs the Enterprise plan. |
| 404 | wallet\_not\_found | The wallet is not verified on this chain by one of your users. |
| 429 | rate\_limit\_exceeded | Rate limit exceeded. |
| 503 | service\_unavailable | Holdings are temporarily unavailable, retry shortly. |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.