Cambrian Total Value Locked API

By Cambrian Network base

GET /api/v1/evm/tvl/status

Total Value Locked (Token Holdings by Address)

Overview

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.

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.
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.
offset integer No 0 Offset the results, allows you to skip a number of rows before starting to return rows.

Response Field Descriptions

Response Field Type Description
chainId UInt16 EVM chain ID the token holding was retrieved from.
ownerAddress FixedString(42) Wallet address that owns the tokens.
tokenAddress FixedString(42) Contract address of the held token.
tokenSymbol String Symbol/ticker of the held token.
tokenAmount Float64 Raw amount of the token held by the wallet.
valueUsd Float64 Current USD value of the token holding.

Examples

1. Retrieve All Token Holdings for a Wallet

This example retrieves every token held by a wallet on Base (chain ID 8453), including tokens with no known USD price.

curl -X GET "https://api.cambrian.org/evm/tvl/status?wallet_address=0xfBB6Eed8e7aa03B138556eeDaF5D271A5E1e43ef&chain_id=8453" \
  -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", "0xcbb7c0000ab88b473b1f5afd9ef808440eed33bf", "cbBTC", 72.85335663, 4677512.761858977],
      [8453, "0xfbb6eed8e7aa03b138556eedaf5d271a5e1e43ef", "0x833589fcd6edb6e08f4c7c32d4f71b54bda02913", "USDC", 3417014.646363, 3417014.646363],
      [8453, "0xfbb6eed8e7aa03b138556eedaf5d271a5e1e43ef", "0x745e91e6db835646f790799e46afb73c459f5af7", "DIGITAL", 301, 565.0151144228093],
      [8453, "0xfbb6eed8e7aa03b138556eedaf5d271a5e1e43ef", "0x3b9efc6f8165812c033618f45a5145cb07548712", "USGR", 75, 0.03814443055110924],
      [8453, "0xfbb6eed8e7aa03b138556eedaf5d271a5e1e43ef", "0x94f68febe9b81e6f44aff39bad8ffaa712879471", "TRUMP", 151.7421, 0.028506361532441616],
      [8453, "0xfbb6eed8e7aa03b138556eedaf5d271a5e1e43ef", "0xc6b4444073f4ee01f707253e6d915b3ff337711b", "ZORA", 100, 0.028099397009084374],
      [8453, "0xfbb6eed8e7aa03b138556eedaf5d271a5e1e43ef", "0xccdc31173d897319bcdd0376b4f64e1819652b57", "CABASE", 1000, 0.01876144236069653],
      [8453, "0xfbb6eed8e7aa03b138556eedaf5d271a5e1e43ef", "0x75618e57ed8c1da6894d0bda2974f1bd96d8c63b", "SROS", 45, 0.01685367157566115],
      [8453, "0xfbb6eed8e7aa03b138556eedaf5d271a5e1e43ef", "0x23a23b6e57d4e35f1584e584d37586b490878763", "USXR", 25, 0.012715165232135998],
      [8453, "0xfbb6eed8e7aa03b138556eedaf5d271a5e1e43ef", "0x68f61fdfbfb72e38341a0ec2ca15043d98294274", "BASEMATE", 25, 0.009419502203740935]
    ],
    "rows": 521
  }
]

Note: This wallet holds 521 total tokens; the data array above has been truncated to the first 10 rows for brevity. The rows field reflects the true total count.

This wallet's largest holding is cbBTC ($4.68M USD), followed by USDC ($3.42M USD), with the remaining 519 tokens holding comparatively negligible USD value — many with a valueUsd of 0 because no price feed is available for them.

2. Filter to Only Priced Tokens with a Result Limit

This example uses hasprice=true combined with limit=10 to return only tokens that have a known USD price, capped at 10 results — useful for quickly computing a wallet's meaningful TVL without noise from unpriced/illiquid tokens.

curl -X GET "https://api.cambrian.org/evm/tvl/status?wallet_address=0xfBB6Eed8e7aa03B138556eeDaF5D271A5E1e43ef&chain_id=8453&hasprice=true&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", "0xcbb7c0000ab88b473b1f5afd9ef808440eed33bf", "cbBTC", 72.85335663, 4677512.761858977],
      [8453, "0xfbb6eed8e7aa03b138556eedaf5d271a5e1e43ef", "0x833589fcd6edb6e08f4c7c32d4f71b54bda02913", "USDC", 3417014.646363, 3417014.646363],
      [8453, "0xfbb6eed8e7aa03b138556eedaf5d271a5e1e43ef", "0x745e91e6db835646f790799e46afb73c459f5af7", "DIGITAL", 301, 565.0151144228093],
      [8453, "0xfbb6eed8e7aa03b138556eedaf5d271a5e1e43ef", "0x3b9efc6f8165812c033618f45a5145cb07548712", "USGR", 75, 0.03814443055110924],
      [8453, "0xfbb6eed8e7aa03b138556eedaf5d271a5e1e43ef", "0x94f68febe9b81e6f44aff39bad8ffaa712879471", "TRUMP", 151.7421, 0.028506361532441616],
      [8453, "0xfbb6eed8e7aa03b138556eedaf5d271a5e1e43ef", "0xc6b4444073f4ee01f707253e6d915b3ff337711b", "ZORA", 100, 0.028099397009084374],
      [8453, "0xfbb6eed8e7aa03b138556eedaf5d271a5e1e43ef", "0xccdc31173d897319bcdd0376b4f64e1819652b57", "CABASE", 1000, 0.01876144236069653],
      [8453, "0xfbb6eed8e7aa03b138556eedaf5d271a5e1e43ef", "0x75618e57ed8c1da6894d0bda2974f1bd96d8c63b", "SROS", 45, 0.01685367157566115],
      [8453, "0xfbb6eed8e7aa03b138556eedaf5d271a5e1e43ef", "0x23a23b6e57d4e35f1584e584d37586b490878763", "USXR", 25, 0.012715165232135998],
      [8453, "0xfbb6eed8e7aa03b138556eedaf5d271a5e1e43ef", "0x68f61fdfbfb72e38341a0ec2ca15043d98294274", "BASEMATE", 25, 0.009419502203740935]
    ],
    "rows": 10
  }
]

With limit=10 applied, the API returns exactly 10 rows (rows: 10), ordered by descending USD value — showing cbBTC and USDC as by far the dominant holdings in this wallet.

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

  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–5 automatically.

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

Related Endpoints

  • /evm/tvl/top-owners - Returns top token holders for a given token address.
  • /evm/aero/v3/pool - Returns current pool TVL (Total Value Locked), Swap Volume, Price volatility and other pool metrics.
  • /evm/uniswap/v3/pool - Returns current pool TVL (Total Value Locked), Swap Volume, Fees APR and other pool metrics.
  • /evm/aero/v2/provider-summary - Provides Aerodrome V2 liquidity-provider summary and portfolio metrics.
  • /evm/dexes - List of DEXes on EVM compatible chains.