Holdings

Query token holdings across organizations, wallets and chains.

Get Holdings

get

Retrieve token holdings data across organizations, wallets and chains. Holdings represent direct token balances held by wallets, excluding DeFi protocol positions.

Supports filtering by wallet, chain, time range, and asset address.

Authorizations

ApiKeyAuth

x-api-KeystringRequired

API key for authentication

Query parameters

chain_idintegerOptional

Blockchain network ID (e.g., 1 for Ethereum mainnet, 137 for Polygon)

Example: 1

chainstringOptional

Blockchain network name (alternative to chain_id)

Example: ethereum

walletstringOptional

Wallet address to filter by

Example: 0x1234567890123456789012345678901234567890Pattern: ^0x[a-fA-F0-9]{40}$

from_datestring · date-timeOptional

Start date for time range filter (ISO 8601 format)

Example: 2024-01-01T00:00:00Z

to_datestring · date-timeOptional

End date for time range filter (ISO 8601 format)

Example: 2024-12-31T23:59:59Z

from_blockstringOptional

Start block number for filtering

Example: 18000000

to_blockstringOptional

End block number for filtering

Example: 18500000

via_proxystringOptional

Proxy contract address if interaction was through a proxy

Example: 0x0000000000000000000000000000000000000000Pattern: ^0x[a-fA-F0-9]{40}$

snapshot_modestring · enumOptional

Filter by snapshot capture mode:

• all: All snapshot types
• daily_only: Daily scheduled snapshots
• interaction_only: Event-driven snapshots on wallet interactions
• harmonized_only: Regularly scheduled harmonized snapshots

Default: allExample: allPossible values:

next_cursorstring · date-timeOptional

Pagination cursor from previous response

Example: 2024-06-15T12:00:00Z

limitinteger · min: 1 · max: 500Optional

Maximum number of results to return (capped at 500)

Default: 500Example: 100

holding_idstringOptional

Unique identifier for a specific holding

Example: eth_0x123...abc_0x456...def_0x000...000

asset_addressstringOptional

Token contract address

Example: 0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48Pattern: ^0x[a-fA-F0-9]{40}$

validatestring · enumOptional

Enable data quality validation (returns only WARNINGS)

Example: truePossible values:

Responses

200

Successful response

application/json

400

Bad Request - Invalid parameters

application/json

404

Not Found - No data found matching the criteria

application/json

500

Internal Server Error

application/json

get

/holdings

HTTPcURLJavaScriptPython

GET /api/holdings HTTP/1.1
x-api-Key: YOUR_API_KEY
Accept: */*

{
  "holdings": [
    {
      "id": "eth_0x123...abc_0x456...def_0x000...000",
      "chain_id": 1,
      "chain": "ethereum",
      "block_number": "18500000",
      "block_timestamp": "2024-01-15T10:30:00Z",
      "asset_address": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
      "wallet_address": "0x1234567890123456789012345678901234567890",
      "via_proxy": "0x0000000000000000000000000000000000000000",
      "asset_decimals": 6,
      "asset_symbol": "USDC",
      "asset_name": "USD Coin",
      "asset_balance_wei": "1000000000",
      "asset_value_usd": 1000,
      "price_usd": 1,
      "oracle_price_usd": 1,
      "snapshot_mode": "daily",
      "interaction_type": "transfer",
      "interaction_tx_hash": "0xdef456...",
      "interaction_delta_asset_balance_wei": "100000000",
      "interaction_delta_asset_value_usd": 100,
      "value_roi_pct": 5.2,
      "value_apr_pct": 3.8,
      "balance_roi_pct": 4.9,
      "balance_apr_pct": 3.5,
      "capital_basis_usd": 5000,
      "capital_basis_wei": "5000000000",
      "realized_pnl_wei": "250000000",
      "realized_pnl_usd": 250,
      "unrealized_pnl_wei": "50000000",
      "unrealized_pnl_usd": 50,
      "cumulative_capital_added_usd": 7500,
      "cumulative_capital_removed_usd": 2500,
      "cumulative_capital_added_wei": "7500000000",
      "cumulative_capital_removed_wei": "2500000000"
    }
  ],
  "page_info": {
    "has_more": true,
    "next_cursor": "2024-06-15T12:00:00Z"
  }
}