Total Value Locked Status
Returns all tokens held by a given EVM wallet address on a specified chain, including token amount and USD value for each holding. This endpoint is useful for portfolio tracking, wallet analysis, and computing an address's total value locked (TVL) across ERC-20 tokens.
GET
https://api.cambrian.org/evm/tvl/status
Parameters
chain_id (integer)
EVM chain ID.
wallet_address* (string)
Address that hold tokens prefixed with 0x
hasprice (boolean)
If true, only tokens with a USD price will be returned
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": "chainId",
"type": "UInt16"
},
{
"name": "ownerAddress",
"type": "FixedString(42)"
},
{
"name": "tokenAddress",
"type": "FixedString(42)"
},
{
"name": "tokenSymbol",
"type": "String"
},
{
"name": "tokenAmount",
"type": "Float64"
},
{
"name": "valueUsd",
"type": "Float64"
}
],
"data": [
[
8453,
"0xfbb6eed8e7aa03b138556eedaf5d271a5e1e43ef",
"0x833589fcd6edb6e08f4c7c32d4f71b54bda02913",
"USDC",
5208823.186388,
5208823.186388
],
[
8453,
"0xfbb6eed8e7aa03b138556eedaf5d271a5e1e43ef",
"0xcbb7c0000ab88b473b1f5afd9ef808440eed33bf",
"cbBTC",
49.00921689,
4038018.931944094
],
[
8453,
"0xfbb6eed8e7aa03b138556eedaf5d271a5e1e43ef",
"0x745e91e6db835646f790799e46afb73c459f5af7",
"DIGITAL",
301,
764.4961389961069
],
[
8453,
"0xfbb6eed8e7aa03b138556eedaf5d271a5e1e43ef",
"0x3b9efc6f8165812c033618f45a5145cb07548712",
"USGR",
100,
0.06881492245377438
],
[
8453,
"0xfbb6eed8e7aa03b138556eedaf5d271a5e1e43ef",
"0x94f68febe9b81e6f44aff39bad8ffaa712879471",
"TRUMP",
151.7421,
0.03857118592561585
],
[
8453,
"0xfbb6eed8e7aa03b138556eedaf5d271a5e1e43ef",
"0x430b7a9583954b853d02a5b70ba64c3d22023896",
"GBOR",
50,
0.033591516324445875
],
[
8453,
"0xfbb6eed8e7aa03b138556eedaf5d271a5e1e43ef",
"0xccdc31173d897319bcdd0376b4f64e1819652b57",
"CABASE",
1000,
0.025385193003869305
],
[
8453,
"0xfbb6eed8e7aa03b138556eedaf5d271a5e1e43ef",
"0x02ee163bbb778086bee0631e205979073bab8dd6",
"USER",
40,
0.020276068496342302
],
[
8453,
"0xfbb6eed8e7aa03b138556eedaf5d271a5e1e43ef",
"0x933714e937be6649b9356a348991fc16f4cd0cd3",
"USMS",
25,
0.018373819001468072
],
[
8453,
"0xfbb6eed8e7aa03b138556eedaf5d271a5e1e43ef",
"0x208e2152184d4bb151d334c35e86d5edbbb80783",
"USOR",
25,
0.017411413621547488
]
],
"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 Token Holdings for a Wallet on Base
This example fetches the tokens held by a wallet address on Base (chain ID 8453), limited to 10 results.
curl
curl -X GET "https://api.cambrian.org/evm/tvl/status?wallet_address=0xfBB6Eed8e7aa03B138556eeDaF5D271A5E1e43ef&limit=10" \
-H "X-API-Key: YOUR_API_KEY" \
-H "Content-Type: application/json"
Response:
JSON
1[
2 {
3 "columns": [
4 {
5 "name": "chainId",
6 "type": "UInt16"
7 },
8 {
9 "name": "ownerAddress",
10 "type": "FixedString(42)"
11 },
12 {
13 "name": "tokenAddress",
14 "type": "FixedString(42)"
15 },
16 {
17 "name": "tokenSymbol",
18 "type": "String"
19 },
20 {
21 "name": "tokenAmount",
22 "type": "Float64"
23 },
24 {
25 "name": "valueUsd",
26 "type": "Float64"
27 }
28 ],
29 "data": [
30 [
31 8453,
32 "0xfbb6eed8e7aa03b138556eedaf5d271a5e1e43ef",
33 "0x833589fcd6edb6e08f4c7c32d4f71b54bda02913",
34 "USDC",
35 5208823.186388,
36 5208823.186388
37 ],
38 [
39 8453,
40 "0xfbb6eed8e7aa03b138556eedaf5d271a5e1e43ef",
41 "0xcbb7c0000ab88b473b1f5afd9ef808440eed33bf",
42 "cbBTC",
43 49.00921689,
44 4038018.931944094
45 ],
46 [
47 8453,
48 "0xfbb6eed8e7aa03b138556eedaf5d271a5e1e43ef",
49 "0x745e91e6db835646f790799e46afb73c459f5af7",
50 "DIGITAL",
51 301,
52 764.4961389961069
53 ],
54 [
55 8453,
56 "0xfbb6eed8e7aa03b138556eedaf5d271a5e1e43ef",
57 "0x3b9efc6f8165812c033618f45a5145cb07548712",
58 "USGR",
59 100,
60 0.06881492245377438
61 ],
62 [
63 8453,
64 "0xfbb6eed8e7aa03b138556eedaf5d271a5e1e43ef",
65 "0x94f68febe9b81e6f44aff39bad8ffaa712879471",
66 "TRUMP",
67 151.7421,
68 0.03857118592561585
69 ],
70 [
71 8453,
72 "0xfbb6eed8e7aa03b138556eedaf5d271a5e1e43ef",
73 "0x430b7a9583954b853d02a5b70ba64c3d22023896",
74 "GBOR",
75 50,
76 0.033591516324445875
77 ],
78 [
79 8453,
80 "0xfbb6eed8e7aa03b138556eedaf5d271a5e1e43ef",
81 "0xccdc31173d897319bcdd0376b4f64e1819652b57",
82 "CABASE",
83 1000,
84 0.025385193003869305
85 ],
86 [
87 8453,
88 "0xfbb6eed8e7aa03b138556eedaf5d271a5e1e43ef",
89 "0x02ee163bbb778086bee0631e205979073bab8dd6",
90 "USER",
91 40,
92 0.020276068496342302
93 ],
94 [
95 8453,
96 "0xfbb6eed8e7aa03b138556eedaf5d271a5e1e43ef",
97 "0x933714e937be6649b9356a348991fc16f4cd0cd3",
98 "USMS",
99 25,
100 0.018373819001468072
101 ],
102 [
103 8453,
104 "0xfbb6eed8e7aa03b138556eedaf5d271a5e1e43ef",
105 "0x208e2152184d4bb151d334c35e86d5edbbb80783",
106 "USOR",
107 25,
108 0.017411413621547488
109 ]
110 ],
111 "rows": 10
112 }
113]
2 {
3 "columns": [
4 {
5 "name": "chainId",
6 "type": "UInt16"
7 },
8 {
9 "name": "ownerAddress",
10 "type": "FixedString(42)"
11 },
12 {
13 "name": "tokenAddress",
14 "type": "FixedString(42)"
15 },
16 {
17 "name": "tokenSymbol",
18 "type": "String"
19 },
20 {
21 "name": "tokenAmount",
22 "type": "Float64"
23 },
24 {
25 "name": "valueUsd",
26 "type": "Float64"
27 }
28 ],
29 "data": [
30 [
31 8453,
32 "0xfbb6eed8e7aa03b138556eedaf5d271a5e1e43ef",
33 "0x833589fcd6edb6e08f4c7c32d4f71b54bda02913",
34 "USDC",
35 5208823.186388,
36 5208823.186388
37 ],
38 [
39 8453,
40 "0xfbb6eed8e7aa03b138556eedaf5d271a5e1e43ef",
41 "0xcbb7c0000ab88b473b1f5afd9ef808440eed33bf",
42 "cbBTC",
43 49.00921689,
44 4038018.931944094
45 ],
46 [
47 8453,
48 "0xfbb6eed8e7aa03b138556eedaf5d271a5e1e43ef",
49 "0x745e91e6db835646f790799e46afb73c459f5af7",
50 "DIGITAL",
51 301,
52 764.4961389961069
53 ],
54 [
55 8453,
56 "0xfbb6eed8e7aa03b138556eedaf5d271a5e1e43ef",
57 "0x3b9efc6f8165812c033618f45a5145cb07548712",
58 "USGR",
59 100,
60 0.06881492245377438
61 ],
62 [
63 8453,
64 "0xfbb6eed8e7aa03b138556eedaf5d271a5e1e43ef",
65 "0x94f68febe9b81e6f44aff39bad8ffaa712879471",
66 "TRUMP",
67 151.7421,
68 0.03857118592561585
69 ],
70 [
71 8453,
72 "0xfbb6eed8e7aa03b138556eedaf5d271a5e1e43ef",
73 "0x430b7a9583954b853d02a5b70ba64c3d22023896",
74 "GBOR",
75 50,
76 0.033591516324445875
77 ],
78 [
79 8453,
80 "0xfbb6eed8e7aa03b138556eedaf5d271a5e1e43ef",
81 "0xccdc31173d897319bcdd0376b4f64e1819652b57",
82 "CABASE",
83 1000,
84 0.025385193003869305
85 ],
86 [
87 8453,
88 "0xfbb6eed8e7aa03b138556eedaf5d271a5e1e43ef",
89 "0x02ee163bbb778086bee0631e205979073bab8dd6",
90 "USER",
91 40,
92 0.020276068496342302
93 ],
94 [
95 8453,
96 "0xfbb6eed8e7aa03b138556eedaf5d271a5e1e43ef",
97 "0x933714e937be6649b9356a348991fc16f4cd0cd3",
98 "USMS",
99 25,
100 0.018373819001468072
101 ],
102 [
103 8453,
104 "0xfbb6eed8e7aa03b138556eedaf5d271a5e1e43ef",
105 "0x208e2152184d4bb151d334c35e86d5edbbb80783",
106 "USOR",
107 25,
108 0.017411413621547488
109 ]
110 ],
111 "rows": 10
112 }
113]
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/evm/tvl/status"
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/evm/tvl/status"
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/evm/tvl/status")
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/evm/tvl/status")
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