Cambrian V2 - Provider Summary API

By Cambrian Network evm

GET /api/v1/evm/aero/v2/provider-summary

Aerodrome V2 Provider Summary

Overview

This endpoint provides a comprehensive overview of a liquidity provider's activity on Aerodrome V2 (an EVM DEX on Base). It returns current summary statistics, portfolio diversity analysis including top pools and token exposure, position size distribution, and historical performance metrics such as fees earned and APR over 7-day and 30-day periods.

Business Value

  • Portfolio Analysis: Understand concentration risk and token exposure across multiple liquidity pools
  • Performance Tracking: Monitor historical fees earned and APR performance over 7-day and 30-day periods
  • Position Management: Analyze position sizes and distribution to optimize capital allocation
  • Risk Assessment: Calculate HHI concentration index to measure portfolio diversification
  • Strategic Planning: Identify top performing pools and fee opportunities for future positions

Endpoint Details

URL: 

https://opabinia.cambrian.network/api/v1/evm/aero/v2/provider-summary

Method: GET
Authentication: Required via X-API-Key header

Query Parameters

Parameter Type Required Default Description
wallet_address string Yes - Liquidity provider address with 0x prefix (e.g., 0x8115afd8dffce5579381ad27524b6feeae917bef)

Response Field Descriptions

Response Field Type Description
providerId String The wallet address of the liquidity provider
totalValueLockedUSD Float64 Total value locked by this provider across all pools, in USD
activePositionCount UInt64 Number of currently active liquidity positions held by the provider
totalFeesEarned7d Float64 Total fees earned by the provider in the last 7 days, in USD
averageAPR7dWeighted Float64 TVL-weighted average APR over the last 7 days, as a percentage
firstPositionTimestamp Nullable(DateTime UTC) Timestamp of the provider's first ever liquidity position
lastActiveTimestamp Nullable(DateTime UTC) Timestamp of the provider's most recent position activity
poolCount UInt64 Number of distinct pools the provider has active positions in
topPoolsData Array(Tuple) Top pools by TVL; each entry is [poolAddress, token0Symbol, token1Symbol, tvlUSD, tvlPercent]
tokenExposure Array(Tuple) Token exposure breakdown; each entry is [tokenAddress, symbol, rawAmount, valueUSD, percentOfPortfolio]
averagePositionSizeUSD Float64 Average size of all active positions in USD
medianPositionSizeUSD Float64 Median size of all active positions in USD
minPositionSizeUSD Float64 Smallest active position size in USD
maxPositionSizeUSD Float64 Largest active position size in USD
hhiConcentrationIndex Float64 Herfindahl-Hirschman Index measuring pool concentration (0 = fully diversified, 1 = fully concentrated)
totalFeesEarned30d Float64 Total fees earned by the provider in the last 30 days, in USD
averageAPR30dWeighted Float64 TVL-weighted average APR over the last 30 days, as a percentage
feeAprByPool30d Array(Tuple) Per-pool fee and APR breakdown over 30 days; each entry is [poolAddress, token0Symbol, token1Symbol, feesUSD, apr]

Examples

1. Get Provider Summary for a Wallet

Retrieve a complete overview of liquidity provision activity for a specific wallet on Aerodrome V2, including portfolio diversity, position sizes, and historical fee performance.

curl -X GET "https://opabinia.cambrian.network/api/v1/evm/aero/v2/provider-summary?wallet_address=0x8115afd8dffce5579381ad27524b6feeae917bef" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json"

Response:

{
  "columns": [
    { "name": "providerId", "type": "String" },
    { "name": "totalValueLockedUSD", "type": "Float64" },
    { "name": "activePositionCount", "type": "UInt64" },
    { "name": "totalFeesEarned7d", "type": "Float64" },
    { "name": "averageAPR7dWeighted", "type": "Float64" },
    { "name": "firstPositionTimestamp", "type": "Nullable(DateTime('UTC'))" },
    { "name": "lastActiveTimestamp", "type": "Nullable(DateTime('UTC'))" },
    { "name": "poolCount", "type": "UInt64" },
    { "name": "topPoolsData", "type": "Array(Tuple(FixedString(42),String,String,Float64,Float64))" },
    { "name": "tokenExposure", "type": "Array(Tuple(FixedString(42),String,Float64,Float64,Float64))" },
    { "name": "averagePositionSizeUSD", "type": "Float64" },
    { "name": "medianPositionSizeUSD", "type": "Float64" },
    { "name": "minPositionSizeUSD", "type": "Float64" },
    { "name": "maxPositionSizeUSD", "type": "Float64" },
    { "name": "hhiConcentrationIndex", "type": "Float64" },
    { "name": "totalFeesEarned30d", "type": "Float64" },
    { "name": "averageAPR30dWeighted", "type": "Float64" },
    { "name": "feeAprByPool30d", "type": "Array(Tuple(FixedString(42),String,String,Float64,Float64))" }
  ],
  "data": [
    [
      "0x8115afd8dffce5579381ad27524b6feeae917bef",
      6.451776499145332,
      3,
      0.014501908869992497,
      11.720352721563152,
      "2025-04-29T09:25:07+00:00",
      "2025-05-06T23:09:49+00:00",
      3,
      [
        ["0xcdac0d6c6c59727a65f871236188350531885c43", "WETH", "USDC", 3.854047380314186, 59.73621964159379],
        ["0x6cdcb1c4a4d1c3c6d054b27ac5b77e89eafb971d", "USDC", "AERO", 2.5977291188311455, 40.2637803584062]
      ],
      [
        ["0x833589fcd6edb6e08f4c7c32d4f71b54bda02913", "USDC", 3.224248708681052, 3.224248708681052, 49.97458776056747],
        ["0x4200000000000000000000000000000000000006", "WETH", 0.0011452272635978018, 1.9305357663667557, 29.92254562169806],
        ["0x940181a94a35a4569e4529a3cdfb74e38fd98631", "AERO", 2.9951122213467682, 1.2969920240975243, 20.102866617734467]
      ],
      2.1505921663817773,
      2.5977291188311455,
      0.0,
      3.854047380314186,
      0.5189587945818713,
      0.05007973998529745,
      9.443964824807043,
      [
        ["0x6cdcb1c4a4d1c3c6d054b27ac5b77e89eafb971d", "USDC", "AERO", 0.02762563960668819, 12.938683487494417],
        ["0xcdac0d6c6c59727a65f871236188350531885c43", "WETH", "USDC", 0.022454100378609267, 7.088432695504171]
      ]
    ]
  ],
  "rows": 1
}

This response shows the wallet 0x8115...7bef has $6.45 USD locked across 3 active positions in 3 pools. Their top pools are WETH/USDC (~59.7% of TVL) and USDC/AERO (~40.3%). The 7-day weighted APR is ~11.7% and the 30-day is ~9.4%. The HHI concentration index of ~0.52 indicates moderate concentration. Per-pool 30-day fee breakdown shows USDC/AERO earned $0.028 at 12.9% APR and WETH/USDC earned $0.022 at 7.1% APR.

2. Analyze Portfolio Concentration

Use this endpoint to evaluate whether a provider is over-concentrated in a single pool, which can increase impermanent loss risk on Aerodrome V2.

curl -X GET "https://opabinia.cambrian.network/api/v1/evm/aero/v2/provider-summary?wallet_address=0x8115afd8dffce5579381ad27524b6feeae917bef" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json"

Response:

{
  "columns": [
    { "name": "hhiConcentrationIndex", "type": "Float64" },
    { "name": "topPoolsData", "type": "Array(Tuple(FixedString(42),String,String,Float64,Float64))" },
    { "name": "tokenExposure", "type": "Array(Tuple(FixedString(42),String,Float64,Float64,Float64))" }
  ],
  "data": [
    [
      0.5189587945818713,
      [
        ["0xcdac0d6c6c59727a65f871236188350531885c43", "WETH", "USDC", 3.854047380314186, 59.73621964159379],
        ["0x6cdcb1c4a4d1c3c6d054b27ac5b77e89eafb971d", "USDC", "AERO", 2.5977291188311455, 40.2637803584062]
      ],
      [
        ["0x833589fcd6edb6e08f4c7c32d4f71b54bda02913", "USDC", 3.224248708681052, 3.224248708681052, 49.97],
        ["0x4200000000000000000000000000000000000006", "WETH", 0.0011452272635978018, 1.9305357663667557, 29.92],
        ["0x940181a94a35a4569e4529a3cdfb74e38fd98631", "AERO", 2.9951122213467682, 1.2969920240975243, 20.10]
      ]
    ]
  ],
  "rows": 1
}

The hhiConcentrationIndex of ~0.52 and topPoolsData reveal the provider is split roughly 60/40 between WETH/USDC and USDC/AERO pools. Token exposure shows ~50% USDC, ~30% WETH, and ~20% AERO by portfolio value, indicating moderate diversification.

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.network/api/v1/evm/aero/v2/provider-summary"
);
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.network/api/v1/evm/aero/v2/provider-summary")
        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

  • /api/v1/evm/aero/v2/pool - Get information for a specific Aerodrome V2 pool address
  • /api/v1/evm/aero/v2/pools - Returns a paginated list of Aerodrome V2 liquidity pools with summary metrics
  • /api/v1/evm/aero/v2/fee-metrics - Shows daily historical fee data over time for a pool
  • /api/v1/evm/aero/v2/pool-volume - Aggregate statistics and hourly volume distribution for a pool
  • /api/v1/evm/aero/v3/pool - Returns current TVL, swap volume, fees APR, and usage stats for an Aerodrome V3 pool