Skip to main content
Retrieve a comprehensive view of all tokens owned by an address, including distribution across wallet holdings and DeFi protocol positions.
PRO Only  This endpoint requires an Octav PRO subscription
Cost: 1 credit per call
Interactive Playground: Test this endpoint in the API Playground. Get your API key at data.octav.fi

​
Endpoint

GET https://api.octav.fi/v1/token-overview

​
Parameters

​
addresses
string
required
EVM or SOL blockchain address
addresses=0x6426af179aabebe47666f345d69fd9079673f6cd
Unlike other endpoints, this currently supports a single address at a time
​
date
string
required
Portfolio snapshot date in YYYY-MM-DD format
date=2024-11-01
Retrieves token holdings as they existed on this specific date

​
Response

​
Token Object

​
image
string
Token logo URL
​
symbol
string
Token ticker symbol (e.g., “ETH”, “USDC”)
​
name
string
Full token name
​
price
string
Token price at the specified date
​
balance
string
Total quantity held across all positions
​
value
string
Total value in USD (balance � price)
​
percentage
string
Percentage of total portfolio value
​
protocolsDetailed
array
Breakdown of token distribution across protocols Each entry contains:
  • key: Protocol identifier
  • name: Protocol display name
  • value: Value held in this protocol
  • balance: Quantity held in this protocol
  • image: Protocol logo URL

​
Example Request

curl -X GET "https://api.octav.fi/v1/token-overview?addresses=0x6426af179aabebe47666f345d69fd9079673f6cd&date=2024-11-01" \
  -H "Authorization: Bearer YOUR_API_KEY"

​
Example Response

[
  {
    "image": "https://assets.coingecko.com/coins/images/279/small/ethereum.png",
    "symbol": "ETH",
    "name": "Ethereum",
    "price": "3245.67",
    "balance": "5.5",
    "value": "17851.19",
    "percentage": "42.5",
    "protocolsDetailed": [
      {
        "key": "wallet",
        "name": "Wallet",
        "value": "10386.68",
        "balance": "3.2",
        "image": "https://..."
      },
      {
        "key": "aave_v3",
        "name": "Aave V3",
        "value": "6491.01",
        "balance": "2.0",
        "image": "https://..."
      },
      {
        "key": "uniswap_v3",
        "name": "Uniswap V3",
        "value": "973.50",
        "balance": "0.3",
        "image": "https://..."
      }
    ]
  },
  {
    "image": "https://assets.coingecko.com/coins/images/6319/small/USD_Coin_icon.png",
    "symbol": "USDC",
    "name": "USD Coin",
    "price": "1.00",
    "balance": "15234.89",
    "value": "15234.89",
    "percentage": "36.3",
    "protocolsDetailed": [
      {
        "key": "wallet",
        "name": "Wallet",
        "value": "5234.89",
        "balance": "5234.89",
        "image": "https://..."
      },
      {
        "key": "aave_v3",
        "name": "Aave V3",
        "value": "10000.00",
        "balance": "10000.00",
        "image": "https://..."
      }
    ]
  },
  {
    "image": "https://assets.coingecko.com/coins/images/877/small/chainlink-new-logo.png",
    "symbol": "LINK",
    "name": "Chainlink",
    "price": "18.45",
    "balance": "234.5",
    "value": "4326.53",
    "percentage": "10.3",
    "protocolsDetailed": [
      {
        "key": "wallet",
        "name": "Wallet",
        "value": "4326.53",
        "balance": "234.5",
        "image": "https://..."
      }
    ]
  }
]

​
Use Cases

  • Token Distribution
  • Protocol Breakdown
  • Token Comparison
  • Concentration Analysis
Visualize token distribution across portfolio:
async function getTokenDistribution(address, date) {
  const response = await fetch(
    `https://api.octav.fi/v1/token-overview?addresses=${address}&date=${date}`,
    {
      headers: {
        'Authorization': `Bearer ${apiKey}`
      }
    }
  );

  const tokens = await response.json();

  // Sort by value
  const sortedTokens = tokens.sort((a, b) =>
    parseFloat(b.value) - parseFloat(a.value)
  );

  // Display distribution
  sortedTokens.forEach(token => {
    console.log(
      `${token.symbol}: ${token.percentage}% ($${token.value})`
    );
  });

  return sortedTokens;
}

const distribution = await getTokenDistribution(address, '2024-11-01');

​
Historical Analysis

The Token Overview endpoint is particularly powerful when combined with historical portfolio subscriptions:

Subscribe to Address

First, subscribe to the address for historical snapshots See Historical Portfolio for details

Query Multiple Dates

Retrieve token overviews for different dates to track changes
const dates = ['2024-09-01', '2024-10-01', '2024-11-01'];
const snapshots = await Promise.all(
  dates.map(date =>
    fetch(
      `https://api.octav.fi/v1/token-overview?addresses=${address}&date=${date}`,
      { headers: { 'Authorization': `Bearer ${apiKey}` } }
    ).then(r => r.json())
  )
);

Analyze Trends

Track how token allocation changes over time
  • New tokens added
  • Tokens sold or removed
  • Balance changes
  • Protocol migration patterns

​
Error Responses

Invalid parameters provided.
{
  "error": "Bad Request",
  "message": "Invalid date format. Use YYYY-MM-DD"
}
Common causes:
  • Missing required parameters
  • Invalid date format
  • Invalid address format
Authentication failed or missing PRO subscription.
{
  "error": "Unauthorized",
  "message": "This endpoint requires Octav PRO subscription"
}
Solution: Upgrade to Octav PRO at data.octav.fi
No historical data available for the specified date.
{
  "error": "Not Found",
  "message": "No snapshot available for this date"
}
Solution: Subscribe to the address for historical snapshots
Insufficient credits.
{
  "error": "Insufficient credits",
  "message": "Please purchase more credits to continue"
}
Solution: Purchase more credits at data.octav.fi

Portfolio

Get current portfolio overview

Historical Portfolio

View full portfolio at specific dates

Transactions

Track token movements over time

Pricing

Learn about PRO subscription