Cambrian Total Value Locked API

By Cambrian Network base

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

  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