Portfolio - Octav Developer Docs

Get comprehensive portfolio data for a blockchain address 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

EVM or SOL wallet address to retrieve portfolio data for

addresses=0x6426af179aabebe47666f345d69fd9079673f6cd

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.), keyed by protocol identifier.Each protocol contains:

key: Protocol identifier
name: Protocol display name
value: Total value in USD
chains: Object keyed by chain identifier. Each chain holds a protocolPositions object whose entries contain the assets[] array.

Asset path: assetByProtocols.<protocol>.chains.<chain>.protocolPositions.<POSITION>.assets[]Each asset contains symbol, name, balance, price, value, decimal, contract, chainKey, and chainContract. The on-chain token address is contract (native assets use the zero address); chainContract is the <chain>:<contract> composite key.

chains

object

Per-chain totals, keyed by chain identifier.Each chain contains:

key: Chain identifier (e.g., “ethereum”, “arbitrum”)
name: Chain display name
chainId: Numeric chain ID
value: Total value on this chain
valuePercentile: Share of total net worth on this chain
totalCostBasis, totalClosedPnl, totalOpenPnl: Cost basis and P&L (or “N/A”)

Example Request

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

Example Response

View Full Response

{
  "address": "0x6426af179aabebe47666f345d69fd9079673f6cd",
  "cashBalance": "0",
  "lastUpdated": "1715173392020",
  "networth": "25123.45",
  "assetByProtocols": {
    "wallet": {
      "name": "Wallet",
      "key": "wallet",
      "value": "25123.45",
      "chains": {
        "ethereum": {
          "name": "Ethereum",
          "key": "ethereum",
          "value": "24962.30",
          "protocolPositions": {
            "WALLET": {
              "name": "wallet",
              "assets": [
                {
                  "balance": "5.5",
                  "symbol": "eth",
                  "name": "ethereum",
                  "price": "3200.50",
                  "value": "17602.75",
                  "decimal": "18",
                  "contract": "0x0000000000000000000000000000000000000000",
                  "chainKey": "ethereum",
                  "chainContract": "ethereum:0x0000000000000000000000000000000000000000"
                },
                {
                  "balance": "7359.55",
                  "symbol": "usdc",
                  "name": "usd coin",
                  "price": "1.00",
                  "value": "7359.55",
                  "decimal": "6",
                  "contract": "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48",
                  "chainKey": "ethereum",
                  "chainContract": "ethereum:0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48"
                }
              ],
              "protocolPositions": [],
              "totalValue": "24962.30",
              "unlockAt": "0"
            }
          }
        },
        "arbitrum": {
          "name": "Arbitrum",
          "key": "arbitrum",
          "value": "161.15",
          "protocolPositions": {
            "WALLET": {
              "name": "wallet",
              "assets": [
                {
                  "balance": "161.15",
                  "symbol": "usdc",
                  "name": "usd coin",
                  "price": "1.00",
                  "value": "161.15",
                  "decimal": "6",
                  "contract": "0xaf88d065e77c8cC2239327C5EDb3A432268e5831",
                  "chainKey": "arbitrum",
                  "chainContract": "arbitrum:0xaf88d065e77c8cC2239327C5EDb3A432268e5831"
                }
              ],
              "protocolPositions": [],
              "totalValue": "161.15",
              "unlockAt": "0"
            }
          }
        }
      }
    }
  },
  "chains": {
    "ethereum": {
      "name": "Ethereum",
      "key": "ethereum",
      "chainId": "1",
      "value": "24962.30",
      "valuePercentile": "99.36",
      "totalCostBasis": "N/A",
      "totalClosedPnl": "N/A",
      "totalOpenPnl": "N/A"
    },
    "arbitrum": {
      "name": "Arbitrum",
      "key": "arbitrum",
      "chainId": "42161",
      "value": "161.15",
      "valuePercentile": "0.64",
      "totalCostBasis": "N/A",
      "totalClosedPnl": "N/A",
      "totalOpenPnl": "N/A"
    }
  }
}

Data Freshness

The Portfolio endpoint uses intelligent caching to balance data freshness with performance:

How Caching Works

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)

Best Practices

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

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}`);
});

Track specific assets across all protocols:

function getAssetTotal(portfolio, symbol) {
  let total = 0;
  let balance = 0;

  Object.values(portfolio.assetByProtocols).forEach(protocol => {
    Object.values(protocol.chains).forEach(chain => {
      Object.values(chain.protocolPositions).forEach(position => {
        position.assets
          .filter(asset => asset.symbol === symbol)
          .forEach(asset => {
            total += parseFloat(asset.value);
            balance += parseFloat(asset.balance);
          });
      });
    });
  });

  return { symbol, balance, value: total };
}

const ethTotal = getAssetTotal(portfolio, 'eth');
console.log(`Total ETH: ${ethTotal.balance} ($${ethTotal.value})`);

Analyze DeFi protocol exposure:

function getProtocolExposure(portfolio) {
  const protocols = Object.values(portfolio.assetByProtocols);
  const totalValue = parseFloat(portfolio.networth);

  return protocols.map(protocol => ({
    name: protocol.name,
    value: parseFloat(protocol.value),
    percentage: (parseFloat(protocol.value) / totalValue * 100).toFixed(2)
  })).sort((a, b) => b.value - a.value);
}

const exposure = getProtocolExposure(portfolio);
exposure.forEach(p => {
  console.log(`${p.name}: $${p.value} (${p.percentage}%)`);
});

Error Responses

400 Bad Request

Invalid parameters provided.

{
  "error": "Bad Request",
  "message": "addresses parameter is required"
}

Common causes:

Missing addresses parameter
Invalid address format

401 Unauthorized

Authentication failed.

{
  "error": "Unauthorized",
  "message": "Invalid API key"
}

Solution: Check your API key in the Authorization header

429 Too Many Requests

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

402 Payment Required

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 this address

Token Overview

Get detailed token breakdown by protocol

Historical Portfolio

View portfolio value at specific dates

Status

Check when portfolio was last synced

​Endpoint

​Parameters

​Response

​Portfolio Object

​Example Request

​Example Response

​Data Freshness

​Use Cases

​Error Responses

​Related Endpoints

Transactions

Token Overview

Historical Portfolio

Status

Endpoint

Parameters

Response

Portfolio Object

Example Request

Example Response

Data Freshness

Use Cases

Error Responses

Related Endpoints