Holder Token Balances (USD)
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.
GET
https://api.cambrian.org/solana/holder-token-balances
Parameters
wallet_address* (string)
Wallet address
limit (integer)
Limit the number of results.
offset (integer)
Offset the results, allows you to skip a number of rows before starting to return rows.
Responses
Code
Description
200
Successful response
Media type: application/vnd.cambrian.table.v1.0.0+json
[
{
"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
}
]
400
Bad Request: Invalid request parameters or malformed request.
401
Unauthorized: Missing or invalid API key. Include X-API-Key header with your request.
403
Forbidden: Invalid API key or insufficient permissions to access this resource.
404
Not Found: Endpoint or resource does not exist.
408
Request Timeout: Request took too long to process. Try again.
500
Internal Server Error: An unexpected error occurred while processing your request.
503
Service Unavailable: The server is temporarily unable to handle the request. Please try again later.
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
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:
JSON
1[
2 {
3 "columns": [
4 {
5 "name": "tokenAddress",
6 "type": "FixedString(44)"
7 },
8 {
9 "name": "balanceRaw",
10 "type": "UInt64"
11 },
12 {
13 "name": "balanceUSD",
14 "type": "Float64"
15 }
16 ],
17 "data": [
18 [
19 "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
20 34685245,
21 34.685245
22 ],
23 [
24 "JUPyiwrYJFskUPiHa7hkeR8VUtAeFoSYbKedZNsDvCN",
25 33386592,
26 6.121212995604027
27 ],
28 [
29 "Es9vMFrzaCERmJfrF4H2FYD4KCoNkY11McCe8BenwNYB",
30 2000000,
31 2
32 ],
33 [
34 "6p6xgHyF7AeE6TZkSmFsko444wqoP15icUSqi2jfGiPN",
35 280000,
36 0.41285158642784164
37 ],
38 [
39 "AQCq97gywgAvsUVMr1SMYCq1pu541evPEPUcXfG8tWsn",
40 50000000000000000,
41 0
42 ],
43 [
44 "DfD3zArdh5GGUaZQJbCw9SHDGTrFSvqpqA4xFQk7qJhu",
45 300000000000000,
46 0
47 ],
48 [
49 "DRvPqvmHhcSSNbgGvjjquntKuucceVRWxsxRDEuyBqT3",
50 198022663070078,
51 0
52 ],
53 [
54 "Cmn4v2wipYV41dkakDvCgFJpxhtaaKt11NyWV8pjSE8A",
55 4000000,
56 0
57 ],
58 [
59 "CeHgUXeNbdhLbKTyMVsRLw2eMvH5rFy4jZ4YS1q43QZB",
60 30000000000000,
61 0
62 ],
63 [
64 "C7EwzBzTwoRrkorimxjgkWiSnkaaZuNavVAgn3hqt9Pd",
65 77000000000,
66 0
67 ]
68 ],
69 "rows": 10
70 }
71]
2 {
3 "columns": [
4 {
5 "name": "tokenAddress",
6 "type": "FixedString(44)"
7 },
8 {
9 "name": "balanceRaw",
10 "type": "UInt64"
11 },
12 {
13 "name": "balanceUSD",
14 "type": "Float64"
15 }
16 ],
17 "data": [
18 [
19 "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
20 34685245,
21 34.685245
22 ],
23 [
24 "JUPyiwrYJFskUPiHa7hkeR8VUtAeFoSYbKedZNsDvCN",
25 33386592,
26 6.121212995604027
27 ],
28 [
29 "Es9vMFrzaCERmJfrF4H2FYD4KCoNkY11McCe8BenwNYB",
30 2000000,
31 2
32 ],
33 [
34 "6p6xgHyF7AeE6TZkSmFsko444wqoP15icUSqi2jfGiPN",
35 280000,
36 0.41285158642784164
37 ],
38 [
39 "AQCq97gywgAvsUVMr1SMYCq1pu541evPEPUcXfG8tWsn",
40 50000000000000000,
41 0
42 ],
43 [
44 "DfD3zArdh5GGUaZQJbCw9SHDGTrFSvqpqA4xFQk7qJhu",
45 300000000000000,
46 0
47 ],
48 [
49 "DRvPqvmHhcSSNbgGvjjquntKuucceVRWxsxRDEuyBqT3",
50 198022663070078,
51 0
52 ],
53 [
54 "Cmn4v2wipYV41dkakDvCgFJpxhtaaKt11NyWV8pjSE8A",
55 4000000,
56 0
57 ],
58 [
59 "CeHgUXeNbdhLbKTyMVsRLw2eMvH5rFy4jZ4YS1q43QZB",
60 30000000000000,
61 0
62 ],
63 [
64 "C7EwzBzTwoRrkorimxjgkWiSnkaaZuNavVAgn3hqt9Pd",
65 77000000000,
66 0
67 ]
68 ],
69 "rows": 10
70 }
71]
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.
Quickstart (Typescript)
bash
npm install @x402/fetch @x402/evm viem
TypeScript
1import { x402Client } from "@x402/core/client";
2import { ExactEvmScheme } from "@x402/evm/exact/client";
3import { wrapFetchWithPayment } from "@x402/fetch";
4import { privateKeyToAccount } from "viem/accounts";
5const signer = privateKeyToAccount(process.env.EVM_PRIVATE_KEY as `0x${string}`);
6const client = new x402Client();
7client.register("eip155:*", new ExactEvmScheme(signer));
8const fetchWithPayment = wrapFetchWithPayment(fetch, client);
9const response = await fetchWithPayment(
10 "https://x402.cambrian.org/solana/holder-token-balances"
11);
12const data = await response.json();
2import { ExactEvmScheme } from "@x402/evm/exact/client";
3import { wrapFetchWithPayment } from "@x402/fetch";
4import { privateKeyToAccount } from "viem/accounts";
5const signer = privateKeyToAccount(process.env.EVM_PRIVATE_KEY as `0x${string}`);
6const client = new x402Client();
7client.register("eip155:*", new ExactEvmScheme(signer));
8const fetchWithPayment = wrapFetchWithPayment(fetch, client);
9const response = await fetchWithPayment(
10 "https://x402.cambrian.org/solana/holder-token-balances"
11);
12const data = await response.json();
Quickstart (Python)
bash
pip install "x402[httpx]"
Python
1import asyncio, os
2from eth_account import Account
3from x402 import x402Client
4from x402.http.clients import x402HttpxClient
5from x402.mechanisms.evm import EthAccountSigner
6from x402.mechanisms.evm.exact.register import register_exact_evm_client
7async def main():
8 client = x402Client()
9 account = Account.from_key(os.getenv("EVM_PRIVATE_KEY"))
10 register_exact_evm_client(client, EthAccountSigner(account))
11 async with x402HttpxClient(client) as http:
12 response = await http.get("https://x402.cambrian.org/solana/holder-token-balances")
13 print(response.json())
14asyncio.run(main())
2from eth_account import Account
3from x402 import x402Client
4from x402.http.clients import x402HttpxClient
5from x402.mechanisms.evm import EthAccountSigner
6from x402.mechanisms.evm.exact.register import register_exact_evm_client
7async def main():
8 client = x402Client()
9 account = Account.from_key(os.getenv("EVM_PRIVATE_KEY"))
10 register_exact_evm_client(client, EthAccountSigner(account))
11 async with x402HttpxClient(client) as http:
12 response = await http.get("https://x402.cambrian.org/solana/holder-token-balances")
13 print(response.json())
14asyncio.run(main())
Payment Flow
- Send a normal request to the endpoint (no API key needed)
- Server returns 402 Payment Required with payment details
- The x402 SDK automatically signs a payment authorization with your wallet
- The SDK resubmits the request with the signed payment
- 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