Cost: 1 credit per call
Interactive Playground: Test this endpoint in the API Playground. Get your API key at data.octav.fi
Endpoint
Parameters
Comma-separated list of EVM or Solana wallet addresses
Example
Response
Returns an array of portfolio objects containing only wallet holdings. The structure follows the same format as the Portfolio endpoint, but filtered to show only thewallet protocol.
Top-Level Fields
The wallet address
Total value of all wallet holdings in USD
Cash balance in USD (typically “0” for wallet-only view)
Realized profit/loss (if available)
Unrealized profit/loss (if available)
Total transaction fees in wei
Total transaction fees in USD
Last sync timestamp (milliseconds since epoch)
Assets organized by protocol - contains only the
wallet key
The wallet protocol contains:name: “Wallet”key: “wallet”value: Total USD valuechains: Holdings organized by blockchain
Chain-level summary of wallet holdings
Each chain contains:
key: Chain identifiername: Chain display namevalue: Total value on this chainchainId: Numeric chain IDvaluePercentile: Percentage of total portfolio
Asset Fields
Each token asset includes:Token balance (in token units)
Token symbol (e.g., “eth”, “uni”)
Token full name
USD value of holding
Current token price in USD
Token contract address (0x000…000 for native tokens)
Blockchain identifier (e.g., “ethereum”, “arbitrum”)
Token decimals
Example Response
Use Cases
- List All Tokens
- Calculate Holdings
- Filter by Value
- Track Fees
Get all tokens in a wallet:
Comparison: Wallet vs Portfolio
What's the Difference?
What's the Difference?
Wallet Endpoint (
/v1/wallet)- Returns only tokens in direct wallet custody
- Shows the
walletprotocol only - Excludes DeFi positions (lending, staking, liquidity pools)
- Best for simple balance checks
/v1/portfolio)- Returns complete portfolio including DeFi positions
- Shows all protocols (wallet, lending, staking, etc.)
- Includes positions on Aave, Uniswap, etc.
- Best for comprehensive portfolio view
- Wallet: Shows 1 ETH in your address
- Portfolio: Shows 1 ETH + 2 ETH deposited in Aave + LP tokens in Uniswap
When to Use Each
When to Use Each
Use /v1/wallet when:
- You only need basic token balances
- Building a simple wallet balance viewer
- Checking liquid/available assets
- Monitoring tokens ready to transfer
- You need complete financial picture
- Tracking DeFi positions
- Calculating total net worth
- Building portfolio analytics dashboard
Response Format
Response Format
Both endpoints return the same data structure:
- Same top-level fields (address, networth, chains)
- Same asset format (balance, value, price)
- Same nested structure
- Wallet:
assetByProtocolscontains onlywalletkey - Portfolio:
assetByProtocolscontains all protocols
Best Practices
Handling Multiple Chains
Handling Multiple Chains
Wallets can hold assets on multiple chains:
Native Token Detection
Native Token Detection
Native tokens (ETH, MATIC, etc.) have special contract address:
Dust Filter
Dust Filter
Filter out very small token amounts (dust):
Price Formatting
Price Formatting
Handle scientific notation in prices:
Common Patterns
Calculate Total by Symbol
Calculate Total by Symbol
Sum up token holdings across chains:
Sort Assets by Value
Sort Assets by Value
Get tokens sorted by USD value:
Check for Specific Token
Check for Specific Token
Find if wallet holds a specific token: