> ## Documentation Index
> Fetch the complete documentation index at: https://docs.octav.fi/llms.txt
> Use this file to discover all available pages before exploring further.

# Token Overview

> Get detailed token breakdown across wallet and protocol positions

Retrieve a comprehensive view of all tokens owned by an address, including distribution across wallet holdings and DeFi protocol positions.

<Warning>
  **PRO Only**  This endpoint requires an Octav PRO subscription
</Warning>

<Info>
  **Cost:** 1 credit per call
</Info>

<Note>
  **Interactive Playground:** Test this endpoint in the [API Playground](/api-reference/tokens/token-overview). Get your API key at [data.octav.fi](https://data.octav.fi/)
</Note>

***

## Endpoint

<CodeGroup>
  ```bash Request theme={null}
  GET https://api.octav.fi/v1/token-overview
  ```

  ```bash Example theme={null}
  curl -X GET "https://api.octav.fi/v1/token-overview?addresses=0x6426af179aabebe47666f345d69fd9079673f6cd&date=2024-11-01" \
    -H "Authorization: Bearer YOUR_API_KEY"
  ```
</CodeGroup>

***

## Parameters

<ParamField query="addresses" type="string" required>
  EVM or SOL blockchain address

  ```
  addresses=0x6426af179aabebe47666f345d69fd9079673f6cd
  ```

  <Note>
    Unlike other endpoints, this currently supports a single address at a time
  </Note>
</ParamField>

<ParamField query="date" type="string" required>
  Portfolio snapshot date in YYYY-MM-DD format

  ```
  date=2024-11-01
  ```

  Retrieves token holdings as they existed on this specific date
</ParamField>

***

## Response

### Token Object

<ResponseField name="image" type="string">
  Token logo URL
</ResponseField>

<ResponseField name="symbol" type="string">
  Token ticker symbol (e.g., "ETH", "USDC")
</ResponseField>

<ResponseField name="name" type="string">
  Full token name
</ResponseField>

<ResponseField name="price" type="string">
  Token price at the specified date
</ResponseField>

<ResponseField name="balance" type="string">
  Total quantity held across all positions
</ResponseField>

<ResponseField name="value" type="string">
  Total value in USD (balance � price)
</ResponseField>

<ResponseField name="percentage" type="string">
  Percentage of total portfolio value
</ResponseField>

<ResponseField name="protocolsDetailed" type="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
</ResponseField>

***

## Example Request

<CodeGroup>
  ```bash cURL theme={null}
  curl -X GET "https://api.octav.fi/v1/token-overview?addresses=0x6426af179aabebe47666f345d69fd9079673f6cd&date=2024-11-01" \
    -H "Authorization: Bearer YOUR_API_KEY"
  ```

  ```javascript JavaScript theme={null}
  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})`);
  });
  ```

  ```python Python theme={null}
  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']})")
  ```

  ```typescript TypeScript theme={null}
  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})`);
  });
  ```
</CodeGroup>

***

## Example Response

<Accordion title="View Full Response" icon="code">
  ```json theme={null}
  [
    {
      "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://..."
        }
      ]
    }
  ]
  ```
</Accordion>

***

## Use Cases

<Tabs>
  <Tab title="Token Distribution" icon="chart-pie">
    Visualize token distribution across portfolio:

    ```javascript theme={null}
    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');
    ```
  </Tab>

  <Tab title="Protocol Breakdown" icon="vault">
    Analyze where tokens are deployed:

    ```javascript theme={null}
    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');
    ```
  </Tab>

  <Tab title="Token Comparison" icon="scale-balanced">
    Compare token holdings across dates:

    ```javascript theme={null}
    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'
    );
    ```
  </Tab>

  <Tab title="Concentration Analysis" icon="bullseye">
    Identify portfolio concentration risk:

    ```javascript theme={null}
    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');
    ```
  </Tab>
</Tabs>

***

## Historical Analysis

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

<Steps>
  <Step title="Subscribe to Address" icon="bell">
    First, subscribe to the address for historical snapshots
    See [Historical Portfolio](/api/endpoints/historical-portfolio) for details
  </Step>

  <Step title="Query Multiple Dates" icon="calendar">
    Retrieve token overviews for different dates to track changes

    ```javascript theme={null}
    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())
      )
    );
    ```
  </Step>

  <Step title="Analyze Trends" icon="chart-line">
    Track how token allocation changes over time

    * New tokens added
    * Tokens sold or removed
    * Balance changes
    * Protocol migration patterns
  </Step>
</Steps>

***

## Error Responses

<AccordionGroup>
  <Accordion title="400 Bad Request" icon="circle-exclamation">
    Invalid parameters provided.

    ```json theme={null}
    {
      "error": "Bad Request",
      "message": "Invalid date format. Use YYYY-MM-DD"
    }
    ```

    **Common causes:**

    * Missing required parameters
    * Invalid date format
    * Invalid address format
  </Accordion>

  <Accordion title="401 Unauthorized" icon="lock">
    Authentication failed or missing PRO subscription.

    ```json theme={null}
    {
      "error": "Unauthorized",
      "message": "This endpoint requires Octav PRO subscription"
    }
    ```

    **Solution:** Upgrade to Octav PRO at [data.octav.fi](https://data.octav.fi/)
  </Accordion>

  <Accordion title="404 Not Found" icon="circle-question">
    No historical data available for the specified date.

    ```json theme={null}
    {
      "error": "Not Found",
      "message": "No snapshot available for this date"
    }
    ```

    **Solution:** Subscribe to the address for historical snapshots
  </Accordion>

  <Accordion title="402 Payment Required" icon="credit-card">
    Insufficient credits.

    ```json theme={null}
    {
      "error": "Insufficient credits",
      "message": "Please purchase more credits to continue"
    }
    ```

    **Solution:** Purchase more credits at [data.octav.fi](https://data.octav.fi/)
  </Accordion>
</AccordionGroup>

***

## Related Endpoints

<CardGroup cols={2}>
  <Card title="Portfolio" icon="wallet" href="/api/endpoints/portfolio">
    Get current portfolio overview
  </Card>

  <Card title="Historical Portfolio" icon="clock" href="/api/endpoints/historical-portfolio">
    View full portfolio at specific dates
  </Card>

  <Card title="Transactions" icon="receipt" href="/api/endpoints/transactions">
    Track token movements over time
  </Card>

  <Card title="Pricing" icon="credit-card" href="/api/pricing">
    Learn about PRO subscription
  </Card>
</CardGroup>