Holder Token Balances (USD)

Overview

This endpoint returns the SPL token balances held by a specific Solana wallet, valued in USD and sorted by balance descending. It provides both raw on-chain balances and their USD equivalents, so you can see a wallet's largest holdings at a glance.

Business Value

• Portfolio Management: Track the complete token portfolio value across different assets for investment analysis
• Risk Assessment: Monitor token concentration and diversification for risk management purposes
• Financial Reporting: Generate accurate USD valuations for accounting and tax reporting requirements
• Trading Decisions: Make informed trading decisions based on current holdings and their market values
• Wealth Tracking: Monitor overall portfolio performance and changes in token values over time

Endpoint Details

URL:

https://api.cambrian.org/solana/holder-token-balances

Method: GET
Authentication: Required via X-API-Key header

Query Parameters

Response Field Descriptions

Examples

1. Retrieve Top Token Holdings for a Wallet

This example fetches the top 10 token balances (by USD value) held by a specific Solana wallet.

curl -X GET "https://api.cambrian.org/solana/holder-token-balances?wallet_address=7VHUFJHWu2CuExkJcJrzhQPJ2oygupTWkL2A2For4BmE&limit=10" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json"

Response:

[
  {
    "columns": [
      {
        "name": "tokenAddress",
        "type": "FixedString(44)"
      },
      {
        "name": "balanceRaw",
        "type": "UInt64"
      },
      {
        "name": "balanceUSD",
        "type": "Float64"
      }
    ],
    "data": [
      [
        "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
        34685245,
        34.685245
      ],
      [
        "JUPyiwrYJFskUPiHa7hkeR8VUtAeFoSYbKedZNsDvCN",
        33386592,
        6.121212995604027
      ],
      [
        "Es9vMFrzaCERmJfrF4H2FYD4KCoNkY11McCe8BenwNYB",
        2000000,
        2
      ],
      [
        "6p6xgHyF7AeE6TZkSmFsko444wqoP15icUSqi2jfGiPN",
        280000,
        0.41285158642784164
      ],
      [
        "AQCq97gywgAvsUVMr1SMYCq1pu541evPEPUcXfG8tWsn",
        50000000000000000,
        0
      ],
      [
        "DfD3zArdh5GGUaZQJbCw9SHDGTrFSvqpqA4xFQk7qJhu",
        300000000000000,
        0
      ],
      [
        "DRvPqvmHhcSSNbgGvjjquntKuucceVRWxsxRDEuyBqT3",
        198022663070078,
        0
      ],
      [
        "Cmn4v2wipYV41dkakDvCgFJpxhtaaKt11NyWV8pjSE8A",
        4000000,
        0
      ],
      [
        "CeHgUXeNbdhLbKTyMVsRLw2eMvH5rFy4jZ4YS1q43QZB",
        30000000000000,
        0
      ],
      [
        "C7EwzBzTwoRrkorimxjgkWiSnkaaZuNavVAgn3hqt9Pd",
        77000000000,
        0
      ]
    ],
    "rows": 10
  }
]

Note: Result collections are limited to 10 items.

The response shows this wallet's largest holding by USD value is USDC (EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v) at roughly $34.69, followed by Jupiter (JUP) worth about $6.12. Several tokens in the list have a balanceUSD of 0, usually because the token has no current price data or is effectively worthless despite a large raw balance.

x402 Payment Option

This endpoint supports pay-per-use access via the x402 payment protocol (v2): pay $0.05 USDC per request using blockchain micropayments. No API key required.

Quick Start (TypeScript)

npm install @x402/fetch @x402/evm viem

import { x402Client } from "@x402/core/client";
import { ExactEvmScheme } from "@x402/evm/exact/client";
import { wrapFetchWithPayment } from "@x402/fetch";
import { privateKeyToAccount } from "viem/accounts";

const signer = privateKeyToAccount(process.env.EVM_PRIVATE_KEY as `0x${string}`);
const client = new x402Client();
client.register("eip155:*", new ExactEvmScheme(signer));

const fetchWithPayment = wrapFetchWithPayment(fetch, client);
const response = await fetchWithPayment(
  "https://x402.cambrian.org/solana/holder-token-balances"
);
const data = await response.json();

Quick Start (Python)

pip install "x402[httpx]"

import asyncio, os
from eth_account import Account
from x402 import x402Client
from x402.http.clients import x402HttpxClient
from x402.mechanisms.evm import EthAccountSigner
from x402.mechanisms.evm.exact.register import register_exact_evm_client

async def main():
    client = x402Client()
    account = Account.from_key(os.getenv("EVM_PRIVATE_KEY"))
    register_exact_evm_client(client, EthAccountSigner(account))

    async with x402HttpxClient(client) as http:
        response = await http.get("https://x402.cambrian.org/solana/holder-token-balances")
        print(response.json())

asyncio.run(main())

Payment Flow

1. Send a normal request to the endpoint (no API key needed)
2. Server returns 402 Payment Required with payment details
3. The x402 SDK automatically signs a payment authorization with your wallet
4. The SDK resubmits the request with the signed payment
5. Server verifies payment and returns the API response

The x402 SDK handles steps 2 through 5 automatically.

Network: Base (chain ID 8453) | Currency: USDC | Price: $0.05 per request