Skip to main content
Get comprehensive portfolio data for blockchain addresses including assets, protocol positions, and net worth across multiple chains.
Interactive Playground: Test this endpoint in the API Playground. Get your API key at data.octav.fi
Cost: 1 credit per call

​
Endpoint

GET https://api.octav.fi/v1/portfolio

​
Parameters

​
addresses
string
required
Comma-separated list of EVM or SOL wallet addresses to retrieve portfolio data for
addresses=0x6426af179aabebe47666f345d69fd9079673f6cd
Multiple addresses:
addresses=0x123...,0x456...,0x789...
​
includeNFTs
boolean
default:"false"
Include NFT holdings in the portfolio responseWhen true, response includes nftsChains and nftsByCollection fields
​
includeImages
boolean
default:"false"
Include image URLs for chains, assets, and protocolsUseful for displaying logos in your application UI
​
includeExplorerUrls
boolean
default:"false"
Include blockchain explorer URLs for assets and transactionsLinks to Etherscan, Arbiscan, etc. for easy navigation
​
waitForSync
boolean
default:"false"
Wait for fresh data if cache is stale
  • false: Return cached data immediately (recommended)
  • true: Wait for sync if data is older than 1 minute

​
Response

​
Portfolio Object

​
address
string
The wallet address
​
networth
string
Total portfolio net worth in USD
​
cashBalance
string
Available cash balance
​
dailyIncome
string
Income generated today
​
dailyExpense
string
Expenses incurred today
​
fees
string
Total fees in native asset
​
feesFiat
string
Total fees in USD
​
lastUpdated
string
Last sync timestamp (milliseconds since epoch)
​
openPnl
string
Unrealized profit/loss (if available, otherwise “N/A”)
​
closedPnl
string
Realized profit/loss (if available, otherwise “N/A”)
​
totalCostBasis
string
Total cost basis of holdings (if available, otherwise “N/A”)
​
assetByProtocols
object
Assets organized by protocol (wallet, lending, staking, etc.)Each protocol contains:
  • key: Protocol identifier
  • name: Protocol display name
  • value: Total value in USD
  • assets[]: Array of asset holdings
​
chains
object
Assets organized by blockchainEach chain contains:
  • key: Chain identifier (e.g., “ethereum”, “arbitrum”)
  • name: Chain display name
  • value: Total value on this chain
  • protocols[]: Protocols with positions on this chain

​
Example Request

curl -X GET "https://api.octav.fi/v1/portfolio?addresses=0x6426af179aabebe47666f345d69fd9079673f6cd&includeImages=true" \
  -H "Authorization: Bearer YOUR_API_KEY"

​
Example Response

{
  "address": "0x6426af179aabebe47666f345d69fd9079673f6cd",
  "cashBalance": "0",
  "dailyIncome": "0",
  "dailyExpense": "0",
  "fees": "0.125",
  "feesFiat": "420.50",
  "lastUpdated": "1715173392020",
  "networth": "45231.89",
  "assetByProtocols": {
    "wallet": {
      "key": "wallet",
      "name": "Wallet",
      "value": "25123.45",
      "assets": [
        {
          "balance": "5.5",
          "symbol": "ETH",
          "price": "3200.50",
          "value": "17602.75",
          "contractAddress": "0x0000000000000000000000000000000000000000",
          "chain": "ethereum"
        },
        {
          "balance": "2.3",
          "symbol": "WETH",
          "price": "3200.50",
          "value": "7361.15",
          "contractAddress": "0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2",
          "chain": "ethereum"
        }
      ]
    },
    "aave_v3": {
      "key": "aave_v3",
      "name": "Aave V3",
      "value": "12500.00",
      "assets": [
        {
          "balance": "10000",
          "symbol": "USDC",
          "price": "1.00",
          "value": "10000.00",
          "contractAddress": "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48",
          "chain": "ethereum"
        },
        {
          "balance": "2500",
          "symbol": "DAI",
          "price": "1.00",
          "value": "2500.00",
          "contractAddress": "0x6b175474e89094c44da98b954eedeac495271d0f",
          "chain": "ethereum"
        }
      ]
    },
    "uniswap_v3": {
      "key": "uniswap_v3",
      "name": "Uniswap V3",
      "value": "7608.44",
      "assets": [
        {
          "balance": "1.2",
          "symbol": "ETH",
          "price": "3200.50",
          "value": "3840.60",
          "chain": "ethereum"
        },
        {
          "balance": "3767.84",
          "symbol": "USDC",
          "price": "1.00",
          "value": "3767.84",
          "chain": "ethereum"
        }
      ]
    }
  },
  "chains": {
    "ethereum": {
      "key": "ethereum",
      "name": "Ethereum",
      "value": "38523.45",
      "protocols": ["wallet", "aave_v3", "uniswap_v3"]
    },
    "arbitrum": {
      "key": "arbitrum",
      "name": "Arbitrum",
      "value": "6708.44",
      "protocols": ["wallet", "gmx"]
    }
  }
}

​
Data Freshness

The Portfolio endpoint uses intelligent caching to balance data freshness with performance:
Cache Duration: 1 minuteWhen data is less than 1 minute old:
  • Cached data returned immediately
  • Response time: under 100ms
When data is more than 1 minute old:
  • Cached data returned immediately
  • Background sync initiated for next request
  • Next request gets fresh data
With waitForSync=true:
  • Waits for sync if data is stale
  • Returns data less than 1 minute old
  • Response time: Variable (1-10 seconds)
For most use cases:
  • Use default waitForSync=false
  • Data fresher than 1 minute is sufficient
  • Fast response times
For real-time tracking:
  • Set waitForSync=true when you need the absolute latest data
  • Accept longer response times
  • Consider rate limits
For background updates:
  • Call endpoint periodically to keep cache warm
  • Background sync ensures next request is fresh

​
Use Cases

  • Portfolio Dashboard
  • Asset Tracking
  • Protocol Analysis
  • Multi-Wallet Bundle
Display portfolio overview with net worth and asset breakdown:
const portfolio = await fetchPortfolio(address);

// Display summary
console.log(`Net Worth: $${portfolio.networth}`);
console.log(`Daily P&L: $${portfolio.dailyIncome - portfolio.dailyExpense}`);

// List protocols
Object.values(portfolio.assetByProtocols).forEach(protocol => {
  console.log(`${protocol.name}: $${protocol.value}`);
});

// Chain distribution
Object.values(portfolio.chains).forEach(chain => {
  console.log(`${chain.name}: $${chain.value}`);
});

​
Error Responses

Invalid parameters provided.
{
  "error": "Bad Request",
  "message": "addresses parameter is required"
}
Common causes:
  • Missing addresses parameter
  • Invalid address format
  • Too many addresses in single request
Authentication failed.
{
  "error": "Unauthorized",
  "message": "Invalid API key"
}
Solution: Check your API key in the Authorization header
Rate limit exceeded.
{
  "error": "Rate limit exceeded",
  "message": "You have exceeded your rate limit",
  "retry_after": 60
}
Solution: Wait for the specified time or implement retry logic
Insufficient credits.
{
  "error": "Insufficient credits",
  "message": "Please purchase more credits to continue"
}
Solution: Purchase more credits at data.octav.fi

Transactions

View transaction history for these addresses

Token Overview

Get detailed token breakdown by protocol

Historical Portfolio

View portfolio value at specific dates

Status

Check when portfolio was last synced