
Official MCP allowing your AI agent to interact with Octav API
Official MCP allowing your AI agent to interact with Octav API
·
██████╗ ██████╗████████╗ █████╗ ██╗ ██╗
██╔═══██╗██╔════╝╚══██╔══╝██╔══██╗██║ ██║
██║ ██║██║ ██║ ███████║██║ ██║
██║ ██║██║ ██║ ██╔══██║╚██╗ ██╔╝
╚██████╔╝╚██████╗ ██║ ██║ ██║ ╚████╔╝
╚═════╝ ╚═════╝ ╚═╝ ╚═╝ ╚═╝ ╚═══╝MCP (Model Context Protocol) server for the Octav cryptocurrency portfolio tracking API. This server enables LLM agents to query portfolio data, transaction history, net worth, and historical snapshots across 20+ blockchains.
Requirements: Node.js 24.22.1+ (recommended), 22.23.4+ or 26.12.1+, each on its own release line. Other majors (for example 25, or 26 before 26.12.1) are not supported. Older releases still trust the compromised eMudhra CA certificates, so api.octav.fi could be impersonated on a hostile network. The server prints a warning at startup if your Node.js is too old.
The easiest way to use this MCP server is with npx (no installation required):
npx octav-api-mcpOr install globally:
npm install -g octav-api-mcp
# or
pnpm add -g octav-api-mcpClone the repository and build from source:
git clone https://github.com/Octav-Labs/octav-api-mcp.git
cd octav-api-mcp
pnpm install
pnpm buildCreate a .env file in the project root:
OCTAV_API_KEY=your-api-key-hereGet your API key from octav.fi.
Add to your Claude Desktop configuration (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):
{
"mcpServers": {
"octav": {
"command": "npx",
"args": ["-y", "octav-api-mcp"],
"env": {
"OCTAV_API_KEY": "your-api-key-here"
}
}
}
}The -y flag automatically confirms package installation if not already cached.
Alternative (if installed globally):
{
"mcpServers": {
"octav": {
"command": "octav-api-mcp",
"env": {
"OCTAV_API_KEY": "your-api-key-here"
}
}
}
}For testing and debugging:
pnpm build
pnpm dlx @modelcontextprotocol/inspector node build/index.jsAll tools use the octav_ prefix for namespace clarity.
octav_get_portfolioGet complete portfolio including wallet holdings and DeFi protocol positions.
Parameters:
addresses (required): Array of wallet addresses (max 10)waitForSync (optional): Wait for a fresh sync when cached data is stale. Default: trueincludeExplorerUrls (optional): Include blockchain explorer URLs. Default: falseCost: 1 credit per address
octav_get_walletGet wallet holdings only (excludes DeFi protocols).
Parameters:
addresses (required): Array of wallet addresses (max 10)Cost: 1 credit per address
octav_get_navGet total net worth (NAV) in specified currency.
Parameters:
addresses (required): Array of wallet addresses (max 10)currency (optional): Currency code (usd, eur, gbp, jpy, cny, eth, btc). Default: usdCost: 1 credit per address
octav_get_token_overviewGet aggregated token distribution across all chains.
Parameters:
addresses (required): Array of wallet addresses (max 10)Cost: 1 credit per address
octav_get_portfolio_at_blockGet a single EVM address's portfolio valued at a specific block. Requires the Portfolio at Block add-on.
Parameters:
address (required): EVM wallet addresschain (required): ethereum, linea or monadblock (required): Block numberCost: 1 credit (plus the add-on)
octav_get_transactionsQuery transaction history with filtering and pagination.
Parameters:
addresses (required): Array of wallet addresses (max 10)chain (optional): Chain keys to filter by, comma-separated (e.g. ethereum,arbitrum)type (optional): Transaction types to filter by, comma-separated (e.g. SWAP,DEPOSIT)protocol (optional): Protocol keys to filter by, comma-separatedinteractingAddresses (optional): Array of counterparty addresses to filter bysearch (optional): Full-text search over token symbols, names and addressestokenId (optional): NFT token IDstartDate (optional): Start date (YYYY-MM-DD)endDate (optional): End date (YYYY-MM-DD)sort (optional): ASC or DESC by timestamp. Default: DESChideSpam (optional): Exclude spam transactionshideDust (optional): Exclude dust transactionsoffset (optional): Pagination offset. Default: 0limit (optional): Number of results (1-250). Default: 50Cost: 1 credit per address
octav_sync_transactionsManually trigger transaction synchronization.
Parameters:
addresses (required): Array of wallet addresses (max 10)Cost: 1 credit per address
octav_get_historicalGet portfolio snapshot for a specific date in the past.
Parameters:
addresses (required): Array of wallet addresses (max 10)date (required): Date for snapshot (YYYY-MM-DD)Cost: 1 credit per address
octav_subscribe_snapshotSubscribe to automatic portfolio snapshots.
Parameters:
addresses (required): Array of wallet addresses (max 10)frequency (required): Snapshot frequency (daily, weekly, monthly)Cost: 1 credit per address
octav_get_statusCheck synchronization status across all chains.
Parameters:
addresses (required): Array of wallet addresses (max 10)Cost: FREE
octav_get_creditsCheck API credit balance and usage.
Parameters: None
Cost: FREE
octav_get_chainsList every supported chain with its key, name, chain id, and whether portfolio and transactions are supported. Chain keys are what the chain parameters of other tools take.
Parameters: None
Cost: FREE
octav_get_chain_protocolsList the protocols tracked on a chain, with the keys used by the protocol filter of octav_get_transactions.
Parameters:
chain (required): Chain keypage (optional): Page number. Default: 1limit (optional): Protocols per page (1-100). Default: 20Cost: FREE
octav_get_contract_protocolIdentify the DeFi protocol a contract address belongs to.
Parameters:
contract (required): Contract address (EVM or Solana)chain (optional): Chain key. Omit to search every chain.Cost: 5 credits, refunded if no protocol is found
octav_get_airdropCheck airdrop eligibility (Solana only).
Parameters:
address (required): Solana wallet addressCost: 1 credit
octav_get_polymarketGet Polymarket prediction market positions.
Parameters:
address (required): Ethereum wallet addressCost: 1 credit
octav_agent_walletGet wallet holdings via x402 payment protocol (for AI agents).
Parameters:
addresses (required): Array of wallet addresses (max 10)Cost: Paid via HTTP 402 payment protocol
octav_agent_portfolioGet full portfolio via x402 payment protocol (for AI agents).
Parameters:
addresses (required): Array of wallet addresses (max 10)Cost: Paid via HTTP 402 payment protocol
octav_get_approvalsGet the ERC-20 token approvals a wallet has granted on one chain. Paginated by cursor.
Parameters:
address (required): EVM wallet addresschain (required): arbitrum, avalanche, base, binance, ethereum, fantom, gnosis, linea, optimism or polygonlimit (optional): Approvals per page (1-100). Default: 25cursor (optional): Cursor from the previous pageCost: 1 credit
Virtual users are balance-tracking or CEX-linked accounts managed in Octav Pro, addressed as virtual:<id>. They require Pro.
octav_list_virtual_usersList the account's virtual users with their virtual:<id> addresses.
Parameters: None
Cost: 1 credit
octav_get_virtual_users_portfolioGet portfolios for virtual users.
Parameters:
addresses (required): Array of virtual:<id> addresses (max 10)aggregated (optional): Return one combined portfolio. Default: falsewaitForSync (optional): Wait for a fresh sync when cached data is stale. Default: trueincludeExplorerUrls (optional): Include blockchain explorer URLs. Default: falseCost: 1 credit per address
The address book is the list of addresses saved to your account, the same list you see in Octav Pro. Entries are keyed by address.
Tools that delete or overwrite account data refuse to run unless called with confirm: true, like --yes in the Octav CLI. Without it they return an error describing what would change.
octav_list_address_bookList every saved address with its label, plan, plan expiry, and paid status.
Parameters: None
Cost: 1 credit
octav_add_address_book_entriesSave addresses to the address book. An address already in the book keeps its existing label.
Parameters:
entries (required): Array of 1-100 { address, label? } objects. Labels are up to 255 characters.Cost: 1 credit
octav_rename_address_book_entryChange the label on a saved address.
Parameters:
address (required): Address of the entrylabel (required): New label, up to 255 characters. An empty string clears it.confirm (required): Must be true, since this replaces the current labelCost: 1 credit
octav_remove_address_book_entryRemove an address from the address book. Entries on a paid plan or authorized by the wallet owner must be removed in Octav Pro instead.
Parameters:
address (required): Address of the entryconfirm (required): Must be trueCost: 1 credit
Bundles are named groups of address book addresses, the same bundles you see in Octav Pro. Every address in a bundle must already be in the address book. By default an account can have 5 bundles of up to 10 addresses each.
octav_list_bundlesList every bundle with its id, name, and addresses.
Parameters: None
Cost: 1 credit
octav_get_bundleGet one bundle by id.
Parameters:
bundleId (required): Bundle idCost: 1 credit
octav_create_bundleCreate a bundle. Names must be unique, and no two bundles may hold exactly the same addresses.
Parameters:
name (required): Bundle name, 1-255 charactersaddresses (required): Array of addresses already in the address bookCost: 1 credit
octav_rename_bundleRename a bundle.
Parameters:
bundleId (required): Bundle idname (required): New name, 1-255 charactersconfirm (required): Must be true, since this replaces the current nameCost: 1 credit
octav_delete_bundleDelete a bundle. Its addresses stay in the address book.
Parameters:
bundleId (required): Bundle idconfirm (required): Must be trueCost: 1 credit
octav_add_bundle_addressAdd an address from the address book to a bundle.
Parameters:
bundleId (required): Bundle idaddress (required): Address to addCost: 1 credit
octav_remove_bundle_addressRemove an address from a bundle. It stays in the address book. To remove a bundle's last address, delete the bundle instead.
Parameters:
bundleId (required): Bundle idaddress (required): Address to removeconfirm (required): Must be trueCost: 1 credit
The server accepts two address formats:
0x followed by 40 hex characters (Ethereum, Polygon, Arbitrum, Base, etc.)The address book and bundle tools also accept Starknet and Tron addresses.
All tools return the Octav API response as JSON.
octav_get_status, octav_get_credits, octav_get_chains and octav_get_chain_protocols are FREEoctav_get_contract_protocol costs 5 credits, refunded if no protocol is foundThe server provides clear error messages for:
pnpm buildpnpm devpnpm testOnce configured with Claude Desktop, you can ask questions like:
Ethereum, Solana, Arbitrum, Base, Polygon, Optimism, BNB Chain, Avalanche, Fantom, Cronos, Gnosis, Celo, Moonbeam, Moonriver, Harmony, Aurora, Metis, Boba, Fuse, Evmos, Kava, and more.
MIT
For API issues or questions, visit octav.fi or check the API documentation.
Pick your client and paste the snippet. Each one is the same server, written the way that client expects it.
claude mcp add octav -- npx -y octav-api-mcp{
"mcpServers": {
"octav": {
"env": {
"OCTAV_API_KEY": ""
},
"args": [
"-y",
"octav-api-mcp"
],
"command": "npx"
}
}
}code --add-mcp '{"name":"octav","env":{"OCTAV_API_KEY":""},"args":["-y","octav-api-mcp"],"command":"npx"}'[mcp_servers.octav]
command = "npx"
args = ["-y", "octav-api-mcp"]Runs locally on your device. Your client starts the server itself, so nothing has to be hosted.
Paste this prompt into your agent. It reads this page and does the setup for you.
Read https://aiagentslisting.com/mcp/octav-api-mcp-server to learn what the "Octav API MCP Server" MCP server does and how to install it. Add it to my coding agent's MCP configuration as documented on that page, then confirm the server connects and list the tools it exposes.Agents can also browse this directory over MCP at https://aiagentslisting.com/api/mcp
npx octav-api-mcpnpm install -g octav-api-mcpThis server runs locally, so we can't read its tool list over the web yet.
We could not run this server: its npm package has not answered in our offline sandbox, which usually means it needs an API key or other configuration to start. The four checks that need a live server are left out, and the grade tops out at B until we can read its tools.
Maintain this server? Claiming proves you own the listing and earns the last 4 points.
Claim this listingPaste this line near the top of your repository's README. The badge always renders the current score.
[](https://aiagentslisting.com/mcp/octav-api-mcp-server)Nothing comparable is listed yet.
v1.2.1Release notesv1.2.0Release notesv1.1.0Release notesv1.0.0Release notesConnect to the AI Agents Listing MCP server at https://aiagentslisting.com/api/mcp using the HTTP transport and complete the sign-in when it asks. Then call the submit_review tool for the listing "octav-api-mcp-server" with a rating from 1 to 5 and a short note on what worked and what did not.No reviews yet
Be the first to share your experience with this tool.
One email a week. New agents, MCP servers and skills, and what is actually getting traction.