Total Value Locked (Status)

Overview

Returns the tokens held by a given EVM wallet address, including each token's contract address, symbol, held amount, and current USD value. This endpoint is useful for computing wallet-level Total Value Locked (TVL) across ERC-20 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

Response Field Descriptions

Examples

1. Get token holdings for a wallet on Base

Retrieves the tokens held by a specific 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",
        4538879.786906,
        4538879.786906
      ],
      [
        8453,
        "0xfbb6eed8e7aa03b138556eedaf5d271a5e1e43ef",
        "0xcbb7c0000ab88b473b1f5afd9ef808440eed33bf",
        "cbBTC",
        30.4103559,
        2563961.017531447
      ],
      [
        8453,
        "0xfbb6eed8e7aa03b138556eedaf5d271a5e1e43ef",
        "0x745e91e6db835646f790799e46afb73c459f5af7",
        "DIGITAL",
        301,
        803.8129794803333
      ],
      [
        8453,
        "0xfbb6eed8e7aa03b138556eedaf5d271a5e1e43ef",
        "0xc3c49edb33df49f8d875f326a3b735689730a749",
        "WESTERN GOLD RESERVE",
        2500000,
        0.06593750996012492
      ],
      [
        8453,
        "0xfbb6eed8e7aa03b138556eedaf5d271a5e1e43ef",
        "0x11df1aa1f7639d9a49dbc2491f6af5d682e5d807",
        "USBR",
        236.4532,
        0.06319319448659168
      ],
      [
        8453,
        "0xfbb6eed8e7aa03b138556eedaf5d271a5e1e43ef",
        "0xa5b77571543c615ba5603b66333c4693349d8e4b",
        "BONKO",
        110000000,
        0.04422311719352871
      ],
      [
        8453,
        "0xfbb6eed8e7aa03b138556eedaf5d271a5e1e43ef",
        "0x94f68febe9b81e6f44aff39bad8ffaa712879471",
        "TRUMP",
        151.7421,
        0.040554888363862424
      ],
      [
        8453,
        "0xfbb6eed8e7aa03b138556eedaf5d271a5e1e43ef",
        "0x430b7a9583954b853d02a5b70ba64c3d22023896",
        "GBOR",
        50,
        0.035319052831535996
      ],
      [
        8453,
        "0xfbb6eed8e7aa03b138556eedaf5d271a5e1e43ef",
        "0xccdc31173d897319bcdd0376b4f64e1819652b57",
        "CABASE",
        1000,
        0.02669071483965819
      ],
      [
        8453,
        "0xfbb6eed8e7aa03b138556eedaf5d271a5e1e43ef",
        "0x02ee163bbb778086bee0631e205979073bab8dd6",
        "USER",
        40,
        0.021318861288971716
      ]
    ],
    "rows": 10
  }
]

Result collections are limited to 10 items. The wallet's largest holding by far is USDC ($4.54M), followed by cbBTC ($2.56M). The remaining tokens contribute negligible USD value.

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

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