Cambrian Total Value Locked API
GET /api/v1/evm/tvl/status
GET /evm/tvl/status
Overview
Returns the tokens held by a given EVM wallet address, including per-token amounts and USD valuations. Use it to compute total value locked (TVL) for an address across ERC-20 token holdings on a specified chain.
Business Value
- Portfolio Analytics: Track complete token holdings across EVM wallets for investment monitoring
- Risk Assessment: Analyze wallet token diversification and concentration risks for due diligence
- Balance Verification: Confirm token holdings for audit, compliance, and verification purposes
- Value Tracking: Monitor USD values of all token positions in real-time
- Token Discovery: Identify all tokens held by a wallet including lesser-known or new tokens
Endpoint Details
URL:
https://api.cambrian.org/evm/tvl/status
Method: GET
Authentication: Required via X-API-Key header
Query Parameters
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
| chain_id | integer | No | 8453 | EVM chain ID. Enum: 1, 8453, 42161, 4663, 56 |
| wallet_address | string | Yes | - | Address that holds tokens, prefixed with 0x |
| hasprice | boolean | No | false | If true, only tokens with a USD price will be returned |
| limit | integer | No | 1000 | Limit the number of results (min 1, max 10000) |
| offset | integer | No | 0 | Offset the results, allows skipping rows before returning results (min 0, max 100000000) |
Response Field Descriptions
| Response Field | Type | Description |
|---|---|---|
| chainId | UInt16 | EVM chain ID the balance was recorded on |
| ownerAddress | FixedString(42) | Wallet address that owns the token balance |
| tokenAddress | FixedString(42) | Contract address of the held token |
| tokenSymbol | String | Symbol of the held token |
| tokenAmount | Float64 | Raw token amount held by the wallet |
| valueUsd | Float64 | USD value of the held token amount |
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 -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:
[
{
"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
}
]
Result collections are limited to 10 items. The response shows the wallet's top holdings on Base, led by USDC ($5.2M) and cbBTC ($4.0M), followed by a long tail of lower-value tokens.
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/evm/tvl/status"
);
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/evm/tvl/status")
print(response.json())
asyncio.run(main())
Payment Flow
- Send a normal request to the endpoint (no API key needed)
- Server returns
402 Payment Requiredwith 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