Token Overview

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

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

Parameters

string

required

EVM or SOL blockchain address

addresses=0x6426af179aabebe47666f345d69fd9079673f6cd

Unlike other endpoints, this currently supports a single address at a time

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

string

Token logo URL

string

Token ticker symbol (e.g., “ETH”, “USDC”)

string

Full token name

string

Token price at the specified date

string

Total quantity held across all positions

string

Total value in USD (balance � price)

string

Percentage of total portfolio value

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"

const address = '0x6426af179aabebe47666f345d69fd9079673f6cd';
const date = '2024-11-01';

const response = await fetch(
  `https://api.octav.fi/v1/token-overview?addresses=${address}&date=${date}`,
  {
    headers: {
      'Authorization': `Bearer ${apiKey}`
    }
  }
);

const tokens = await response.json();
console.log(`Found ${tokens.length} tokens`);

// Display top holdings
tokens.slice(0, 5).forEach(token => {
  console.log(`${token.symbol}: ${token.balance} ($${token.value})`);
});

import requests

address = '0x6426af179aabebe47666f345d69fd9079673f6cd'
date = '2024-11-01'

response = requests.get(
    'https://api.octav.fi/v1/token-overview',
    params={
        'addresses': address,
        'date': date
    },
    headers={'Authorization': f'Bearer {api_key}'}
)

tokens = response.json()
print(f'Found {len(tokens)} tokens')

# Display top holdings
for token in tokens[:5]:
    print(f"{token['symbol']}: {token['balance']} (${token['value']})")

interface ProtocolPosition {
  key: string;
  name: string;
  value: string;
  balance: string;
  image?: string;
}

interface Token {
  image?: string;
  symbol: string;
  name: string;
  price: string;
  balance: string;
  value: string;
  percentage: string;
  protocolsDetailed: ProtocolPosition[];
}

const address = '0x6426af179aabebe47666f345d69fd9079673f6cd';
const date = '2024-11-01';

const response = await fetch(
  `https://api.octav.fi/v1/token-overview?addresses=${address}&date=${date}`,
  {
    headers: {
      'Authorization': `Bearer ${apiKey}`
    }
  }
);

const tokens: Token[] = await response.json();
console.log(`Found ${tokens.length} tokens`);

// Display top holdings
tokens.slice(0, 5).forEach(token => {
  console.log(`${token.symbol}: ${token.balance} ($${token.value})`);
});

Example Response

View Full 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');

Analyze where tokens are deployed:

async function analyzeTokenDeployment(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();

  // Aggregate by protocol
  const protocolTotals = {};

  tokens.forEach(token => {
    token.protocolsDetailed.forEach(protocol => {
      if (!protocolTotals[protocol.name]) {
        protocolTotals[protocol.name] = 0;
      }
      protocolTotals[protocol.name] += parseFloat(protocol.value);
    });
  });

  // Display protocol exposure
  Object.entries(protocolTotals)
    .sort((a, b) => b[1] - a[1])
    .forEach(([protocol, value]) => {
      console.log(`${protocol}: $${value.toFixed(2)}`);
    });

  return protocolTotals;
}

const deployment = await analyzeTokenDeployment(address, '2024-11-01');

Compare token holdings across dates:

async function compareTokenHoldings(address, date1, date2) {
  const [snapshot1, snapshot2] = await Promise.all([
    fetch(
      `https://api.octav.fi/v1/token-overview?addresses=${address}&date=${date1}`,
      { headers: { 'Authorization': `Bearer ${apiKey}` } }
    ).then(r => r.json()),
    fetch(
      `https://api.octav.fi/v1/token-overview?addresses=${address}&date=${date2}`,
      { headers: { 'Authorization': `Bearer ${apiKey}` } }
    ).then(r => r.json())
  ]);

  // Create maps for easy comparison
  const tokens1 = new Map(
    snapshot1.map(t => [t.symbol, parseFloat(t.balance)])
  );
  const tokens2 = new Map(
    snapshot2.map(t => [t.symbol, parseFloat(t.balance)])
  );

  // Find changes
  const allSymbols = new Set([...tokens1.keys(), ...tokens2.keys()]);
  const changes = [];

  allSymbols.forEach(symbol => {
    const balance1 = tokens1.get(symbol) || 0;
    const balance2 = tokens2.get(symbol) || 0;
    const change = balance2 - balance1;

    if (change !== 0) {
      changes.push({
        symbol,
        change,
        percentChange: balance1 > 0 ? (change / balance1 * 100) : 0
      });
    }
  });

  // Display changes
  changes
    .sort((a, b) => Math.abs(b.change) - Math.abs(a.change))
    .forEach(({ symbol, change, percentChange }) => {
      const direction = change > 0 ? '=�' : '=�';
      console.log(
        `${direction} ${symbol}: ${change > 0 ? '+' : ''}${change.toFixed(4)} ` +
        `(${percentChange > 0 ? '+' : ''}${percentChange.toFixed(2)}%)`
      );
    });

  return changes;
}

const changes = await compareTokenHoldings(
  address,
  '2024-10-01',
  '2024-11-01'
);

Identify portfolio concentration risk:

async function analyzeConcentration(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();

  // Calculate concentration metrics
  const totalValue = tokens.reduce(
    (sum, t) => sum + parseFloat(t.value),
    0
  );

  // Top token concentration
  const topToken = tokens.reduce((max, t) =>
    parseFloat(t.value) > parseFloat(max.value) ? t : max
  );

  // Top 3 concentration
  const top3Value = tokens
    .slice(0, 3)
    .reduce((sum, t) => sum + parseFloat(t.value), 0);

  // Top 5 concentration
  const top5Value = tokens
    .slice(0, 5)
    .reduce((sum, t) => sum + parseFloat(t.value), 0);

  console.log('Portfolio Concentration:');
  console.log(`Top token: ${topToken.symbol} - ${topToken.percentage}%`);
  console.log(`Top 3 tokens: ${(top3Value / totalValue * 100).toFixed(2)}%`);
  console.log(`Top 5 tokens: ${(top5Value / totalValue * 100).toFixed(2)}%`);
  console.log(`Total tokens: ${tokens.length}`);

  return {
    topToken: topToken.percentage,
    top3: (top3Value / totalValue * 100).toFixed(2),
    top5: (top5Value / totalValue * 100).toFixed(2),
    totalTokens: tokens.length
  };
}

const concentration = await analyzeConcentration(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

400 Bad Request

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

401 Unauthorized

Authentication failed or missing PRO subscription.

{
  "error": "Unauthorized",
  "message": "This endpoint requires Octav PRO subscription"
}

Solution: Upgrade to Octav PRO at data.octav.fi

404 Not Found

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

402 Payment Required

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

Getting Started

Endpoints

Playground

AI Development

Migrate to Octav

Reference

Endpoint

Parameters

Response

Token Object

Example Request

Example Response

Use Cases

Historical Analysis

Error Responses

Portfolio

Historical Portfolio

Transactions

Pricing

​Endpoint

​Parameters

​Response

​Token Object

​Example Request

​Example Response

​Use Cases

​Historical Analysis

​Error Responses

​Related Endpoints

Portfolio

Historical Portfolio

Transactions

Pricing

Endpoint

Parameters

Response

Token Object

Example Request

Example Response

Use Cases

Historical Analysis

Error Responses

Related Endpoints