> ## 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 wallet of your users with USD value, read from the chain.

The current token balances of a wallet of your users 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.

> [!NOTE]
>
> White-Label: unverified wallets of your platform users work here too, while `wallet_trust` is `all`. `profile.wallet_verified` tells you whether the wallet is payment-verified, so you can show a badge. With `wallet_trust: verified_only` only payment-verified wallets are answered.

## Query Parameters

**blockchain** `string` *required*

Chain of the wallet. One of solana, bnb, base, eth, rh.

**address** `string` *required*

A wallet of one of your users on this chain: payment-verified, or an unverified wallet of one of your [platform users](https://docs.cabalspy.xyz/cabalspy-id/white-label.md#unverified-and-verified-wallets) while your instance's `wallet_trust` is `all`.

**scope** `string` (default: instance)

`global` allows any CabalSpy ID wallet. Enterprise plan only.

**instance** `string`

Your Instance ID. Only needed when your account has several instances.

**api\_key** `string` *required*

Your API key. Alternatively pass it as an Authorization Bearer header.

## Usage Example

```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);
```

## Response

**success** `boolean`

True on success.

**data** `object`

**data**

**wallet** `string`

The wallet address.

**blockchain** `string`

Chain.

**profile** `object`

The owner's profile, the same fields as on the [tracker](https://docs.cabalspy.xyz/cabalspy-id/tracker.md).

**active\_holdings** `object`

**active\_holdings**

**tokens** `array`

**token**

**token\_address** `string`

Token mint or contract.

**token\_name** `string`

Token name.

**symbol** `string`

Token symbol.

**logo** `string`

Token logo URL.

**amount** `string`

Raw balance in the token's smallest unit.

**amount\_formatted** `string`

Balance in whole tokens.

**decimals** `integer`

Token decimals.

**price\_usd** `number`

Token price in USD.

**value\_usd** `number`

Value of the balance in USD.

**verified\_contract** `boolean`

Reserved, currently null.

**count** `integer`

Number of tokens.

**total\_value\_usd** `number`

Total value of all tokens in USD.

**last\_updated** `string`

When the balances were read.

**stale** `boolean`

True when the cached balances are older than 30 seconds.

**loading** `boolean`

Always false, kept for compatibility with the CabalSpy API.

```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"
  }
}
```

## 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. |
| 403 | product\_not\_enabled | The key is not enabled for the CabalSpy ID API (API keys page, Works with). |
| 403 | scope\_not\_allowed | scope=global needs the Enterprise plan. |
| 404 | wallet\_not\_found | The wallet does not count on this chain for one of your users: not payment-verified, and not an unverified wallet of one of your platform users (or `wallet_trust` is `verified_only`). |
| 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.