Crypto Portfolio MCP Server

The official Octav MCP server lets AI assistants query portfolio data, transaction history, net worth, token approvals, and historical snapshots across 20+ blockchains, and manage your address book and bundles — directly from your conversation.

Quick Install — Run the MCP server with no installation required:

npx octav-api-mcp

Features

Portfolio & Holdings

Multi-chain portfolio aggregation

Wallet balances and DeFi positions
Net worth in multiple currencies
Portfolio valued at a past block

Transaction History

Complete transaction records

Filter by chain, type, protocol, and counterparty
Text search, NFT token ID, spam and dust filters
Up to 250 results per query

Historical Snapshots

Time-series portfolio data

Point-in-time snapshots
Automatic daily subscriptions
Performance tracking

Address Book & Bundles

Manage saved addresses

Save, label, and remove addresses
Group them into named bundles
Confirmation before any delete or overwrite

Approvals & Contracts

Security and protocol data

ERC-20 token approvals per chain
Find the protocol behind a contract
Supported chains and protocols

Specialized Data

Additional capabilities

Solana airdrop eligibility
Polymarket positions
Virtual users (Pro)

Installation

npx (Recommended)
npm
pnpm

No installation required — run directly:

npx octav-api-mcp

Install globally:

npm install -g octav-api-mcp

Then run:

octav-api-mcp

Install globally:

pnpm add -g octav-api-mcp

Then run:

octav-api-mcp

Configuration

You’ll need an Octav API key. Get one at data.octav.fi.

Claude Desktop

macOS
Windows

Edit ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "octav": {
      "command": "npx",
      "args": ["-y", "octav-api-mcp"],
      "env": {
        "OCTAV_API_KEY": "your-api-key-here"
      }
    }
  }
}

Edit %APPDATA%\Claude\claude_desktop_config.json:

{
  "mcpServers": {
    "octav": {
      "command": "npx",
      "args": ["-y", "octav-api-mcp"],
      "env": {
        "OCTAV_API_KEY": "your-api-key-here"
      }
    }
  }
}

Cursor

Go to Cursor Settings > MCP and add a new global MCP server:

{
  "mcpServers": {
    "octav": {
      "command": "npx",
      "args": ["-y", "octav-api-mcp"],
      "env": {
        "OCTAV_API_KEY": "your-api-key-here"
      }
    }
  }
}

VS Code (Copilot)

Add to your VS Code settings.json:

{
  "mcp": {
    "servers": {
      "octav": {
        "command": "npx",
        "args": ["-y", "octav-api-mcp"],
        "env": {
          "OCTAV_API_KEY": "your-api-key-here"
        }
      }
    }
  }
}

Claude Code

Add the MCP server with the Claude Code CLI, passing your API key:

claude mcp add octav -e OCTAV_API_KEY=your-api-key-here -- npx -y octav-api-mcp

Available Tools

The MCP server exposes 30 tools organized by category. Most tools cost 1 credit per address.

Portfolio & Holdings

octav_get_portfolio

Complete portfolio including wallet holdings and DeFi positions across 20+ blockchains.

Parameter	Type	Required	Description
`addresses`	string[]	Yes	Wallet addresses (EVM `0x...` or Solana base58). Max 10.
`waitForSync`	boolean	No	Wait for a fresh sync when cached data is stale. Defaults to `true`.
`includeExplorerUrls`	boolean	No	Include block explorer URLs for assets and transactions. Defaults to `false`.

Cost: 1 credit per address

"Show me the full portfolio for 0x123..."

octav_get_wallet

Wallet token balances only (excludes DeFi protocol positions).

Parameter	Type	Required	Description
`addresses`	string[]	Yes	Wallet addresses. Max 10.

Cost: 1 credit per address

"What tokens does 0x123... hold?"

octav_get_nav

Total net worth in a specified currency.

Parameter	Type	Required	Description
`addresses`	string[]	Yes	Wallet addresses. Max 10.
`currency`	string	No	Fiat: `USD`, `EUR`, `CAD`, `AED`, `CHF`, `SGD`. Crypto: `ETH`, `SOL`, `cbBTC`, `EURC`, `BNB`. Defaults to `USD`.

Cost: 1 credit per address

"What's the total net worth of 0x123... in EUR?"

octav_get_token_overview

Aggregated token distribution across all chains.

Parameter	Type	Required	Description
`addresses`	string[]	Yes	Wallet addresses. Max 10.
`date`	string	Yes	Snapshot date in `YYYY-MM-DD` format.

Cost: 1 credit per address

"Show me the token breakdown for 0x123... as of 2025-01-15"

octav_get_portfolio_at_block

A single EVM address’s portfolio, with every balance and price valued at a specific block.

Parameter	Type	Required	Description
`address`	string	Yes	EVM wallet address (`0x...`).
`chain`	string	Yes	`ethereum`, `linea`, or `monad`.
`block`	integer	Yes	Block number.

Cost: 1 credit, plus the Portfolio at Block add-on. See Portfolio at Block.

"What was 0x123... worth at Ethereum block 19000000?"

Transactions

octav_get_transactions

Query transaction history with filtering and pagination.

Parameter	Type	Required	Description
`addresses`	string[]	Yes	Wallet addresses. Max 10.
`chain`	string	No	Chain keys, comma-separated (e.g., `ethereum,arbitrum`). See `octav_get_chains`.
`type`	string	No	Transaction types, comma-separated (e.g., `SWAP,DEPOSIT`). See Transaction Types.
`protocol`	string	No	Protocol keys, comma-separated. See `octav_get_chain_protocols`.
`interactingAddresses`	string[]	No	Only transactions with these counterparty addresses.
`search`	string	No	Full-text search over token symbols, names, and addresses.
`tokenId`	string	No	NFT token ID.
`startDate`	string	No	Start date (`YYYY-MM-DD`).
`endDate`	string	No	End date (`YYYY-MM-DD`).
`sort`	string	No	`ASC` or `DESC` by timestamp. Defaults to `DESC`.
`hideSpam`	boolean	No	Exclude spam transactions.
`hideDust`	boolean	No	Exclude dust transactions.
`limit`	number	No	Results per request (1–250, default 50).
`offset`	number	No	Pagination offset (default 0).

Cost: 1 credit per address

"Show me the last 20 swaps on Ethereum for 0x123..., without spam"

octav_sync_transactions

Trigger manual transaction synchronization for immediate indexing.

Parameter	Type	Required	Description
`addresses`	string[]	Yes	Wallet addresses. Max 10.

Cost: 1 credit per address

"Sync the latest transactions for 0x123..."

Historical & Snapshots

octav_get_historical

Portfolio snapshot for a specific past date.

Parameter	Type	Required	Description
`addresses`	string[]	Yes	Wallet addresses. Max 10.
`date`	string	Yes	Date in `YYYY-MM-DD` format.

Cost: 1 credit per address

"What was my portfolio worth on 2024-12-31?"

Subscribe to automatic daily portfolio snapshots.

Parameter	Type	Required	Description
`addresses`	string[]	Yes	Wallet addresses. Max 10.
`description`	string	No	Optional label for the subscription.

Cost: 1,200 credits

"Subscribe 0x123... to daily snapshots"

Metadata

octav_get_status

Check sync status of addresses across all chains.

Parameter	Type	Required	Description
`addresses`	string[]	Yes	Wallet addresses. Max 10.

Cost: Free

"Is 0x123... fully synced?"

octav_get_credits

Check API credit balance and usage.No parameters required.Cost: Free

"How many API credits do I have left?"

octav_get_chains

Every supported chain, with the key that other tools’ chain parameters take.Returns each chain’s key, name, chain ID, and whether portfolio and transactions are supported. No parameters required.Cost: Free

"Which chains does Octav support for transactions?"

octav_get_chain_protocols

Protocols Octav tracks on a chain, with the keys the protocol filter takes.

Parameter	Type	Required	Description
`chain`	string	Yes	Chain key (e.g., `ethereum`, `solana`).
`page`	number	No	Page number. Defaults to 1.
`limit`	number	No	Protocols per page (1–100). Defaults to 20.

Cost: Free

"Which protocols does Octav track on Base?"

octav_get_contract_protocol

Find which DeFi protocol a contract address belongs to.

Parameter	Type	Required	Description
`contract`	string	Yes	Contract address (EVM `0x...` or Solana base58).
`chain`	string	No	Chain key. Omit to search every chain.

Cost: 5 credits, refunded if no protocol is found

"Which protocol does contract 0x1f98431c8ad98523631ae4a59f267346ea31f984 belong to?"

Specialized

octav_get_approvals

ERC-20 token approvals a wallet has granted to spender contracts on one chain.

Parameter	Type	Required	Description
`address`	string	Yes	EVM wallet address (`0x...`).
`chain`	string	Yes	`arbitrum`, `avalanche`, `base`, `binance`, `ethereum`, `fantom`, `gnosis`, `linea`, `optimism`, or `polygon`.
`limit`	number	No	Approvals per page (1–100). Defaults to 25.
`cursor`	string	No	Cursor from the previous response, to fetch the next page.

Cost: 1 credit

"Which contracts can spend my tokens on Ethereum? My wallet is 0x123..."

octav_get_airdrop

Check airdrop eligibility for a Solana address.

Parameter	Type	Required	Description
`address`	string	Yes	Solana wallet address (base58).

Cost: 1 credit

"Check airdrop eligibility for my Solana wallet"

octav_get_polymarket

Get Polymarket prediction market positions.

Parameter	Type	Required	Description
`address`	string	Yes	Ethereum wallet address (`0x...`).

Cost: 1 credit

"Show my Polymarket positions for 0x123..."

Agents with their own x402 wallet can also call Octav’s pay-per-call endpoints directly, without an API key. See Agent Endpoints (x402).

Virtual Users

Virtual users are balance-tracking or CEX-linked accounts managed in Octav Pro, addressed as virtual:<id>. They require Pro. See Virtual Users.

octav_list_virtual_users

The virtual users on your account, with their virtual:<id> address, type, and label.No parameters required.Cost: 1 credit

"List my virtual users"

octav_get_virtual_users_portfolio

Portfolios for virtual users, in the same shape as octav_get_portfolio.

Parameter	Type	Required	Description
`addresses`	string[]	Yes	`virtual:<id>` addresses from `octav_list_virtual_users`. Max 10.
`aggregated`	boolean	No	Return one portfolio combined across all the virtual users. Defaults to `false`.
`waitForSync`	boolean	No	Wait for a fresh sync when cached data is stale. Defaults to `true`.
`includeExplorerUrls`	boolean	No	Include block explorer URLs. Defaults to `false`.

Cost: 1 credit per address

"Show the combined portfolio of my virtual users"

Address Book

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. See Address Book.

Tools that delete or overwrite account data run only when called with confirm: true. Without it they change nothing and return a message describing the change, so your assistant can check with you first.

octav_list_address_book

Every saved address with its label, plan, plan expiry, and paid status.No parameters required.Cost: 1 credit

"Which addresses are in my address book?"

octav_add_address_book_entries

Save addresses to the address book. An address already in the book keeps its existing label. Accepts EVM, Solana, and Tron addresses. Accounts without a paid plan can save up to 50 addresses.

Parameter	Type	Required	Description
`entries`	object[]	Yes	1–100 entries, each `{ "address": "...", "label": "..." }`. `label` is optional, up to 255 characters.

Cost: 1 credit

"Save 0x123... to my address book as Treasury"

octav_rename_address_book_entry

Change the label on a saved address.

Parameter	Type	Required	Description
`address`	string	Yes	Address of the entry.
`label`	string	Yes	New label, up to 255 characters. An empty string clears it.
`confirm`	boolean	Yes	Must be `true`, since this replaces the current label.

Cost: 1 credit

octav_remove_address_book_entry

Remove an address from the address book. Entries on a paid plan or authorized by the wallet owner must be removed in Octav Pro instead.

Parameter	Type	Required	Description
`address`	string	Yes	Address of the entry.
`confirm`	boolean	Yes	Must be `true`.

Cost: 1 credit

Bundles

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. See Bundles.

octav_list_bundles

Every bundle with its ID, name, and addresses.No parameters required.Cost: 1 credit

"Show my bundles and the total value of each"

octav_get_bundle

One bundle by ID.

Parameter	Type	Required	Description
`bundleId`	string	Yes	Bundle ID.

Cost: 1 credit

octav_create_bundle

Create a bundle. Names must be unique, and no two bundles may hold exactly the same addresses. Bundles created through the API are private.

Parameter	Type	Required	Description
`name`	string	Yes	Bundle name, 1–255 characters.
`addresses`	string[]	Yes	Addresses already in the address book.

Cost: 1 credit

"Create a bundle called Client A with 0x123... and 0x456..."

octav_rename_bundle

Rename a bundle.

Parameter	Type	Required	Description
`bundleId`	string	Yes	Bundle ID.
`name`	string	Yes	New name, 1–255 characters.
`confirm`	boolean	Yes	Must be `true`, since this replaces the current name.

Cost: 1 credit

octav_delete_bundle

Delete a bundle. Its addresses stay in the address book.

Parameter	Type	Required	Description
`bundleId`	string	Yes	Bundle ID.
`confirm`	boolean	Yes	Must be `true`.

Cost: 1 credit

octav_add_bundle_address

Add an address from the address book to a bundle.

Parameter	Type	Required	Description
`bundleId`	string	Yes	Bundle ID.
`address`	string	Yes	Address to add.

Cost: 1 credit

octav_remove_bundle_address

Remove an address from a bundle. It stays in the address book. To remove a bundle’s last address, delete the bundle instead.

Parameter	Type	Required	Description
`bundleId`	string	Yes	Bundle ID.
`address`	string	Yes	Address to remove.
`confirm`	boolean	Yes	Must be `true`.

Cost: 1 credit

Example Prompts

Once the MCP server is connected, you can ask your AI assistant questions like:

"What's the total value of my portfolio at 0xABC...?"

"Show me all swap transactions on Arbitrum for the past month"

"Compare my portfolio value today vs. 30 days ago"

"Which contracts can spend my tokens on Ethereum?"

"Save 0xABC... to my address book as Treasury and add it to my Client A bundle"

"Check if my Solana wallet is eligible for any airdrops"

"How many API credits do I have left?"

Error Handling

The MCP server returns clear error messages for common issues:

Error	Cause	Solution
Invalid address format	Address doesn’t match the format the tool accepts	Use `0x...` (40 hex chars) for EVM or base58 for Solana. Address book and bundle tools also accept Tron.
Confirmation required	A tool that deletes or overwrites data was called without `confirm: true`	Check with the user, then call it again with `confirm: true`
Authentication failure	Missing or invalid API key	Check your `OCTAV_API_KEY` environment variable
Insufficient credits	Not enough credits for the request	Purchase more at data.octav.fi
Rate limit exceeded	Too many requests per minute	Wait and retry — the server includes retry guidance
API error with a code	The API rejected the request, e.g. `BUNDLE_NAME_TAKEN`	The message names the problem; see Address Book and Bundles for each code

Resources

GitHub

Source code and issues

API Docs

Full REST API reference

Pricing

Credit packages and costs

Getting Started

Endpoints

Playground

AI Development

Migrate to Octav

Reference

Features

Portfolio & Holdings

Transaction History

Historical Snapshots

Address Book & Bundles

Approvals & Contracts

Specialized Data

Installation

Configuration

Claude Desktop

Cursor

VS Code (Copilot)

Claude Code

Available Tools

Portfolio & Holdings

Transactions

Historical & Snapshots

Metadata

Specialized

Virtual Users

Address Book

Bundles

Example Prompts

Error Handling

Resources

GitHub

API Docs

Pricing

​Features

Portfolio & Holdings

Transaction History

Historical Snapshots

Address Book & Bundles

Approvals & Contracts

Specialized Data

​Installation

​Configuration

​Claude Desktop

​Cursor

​VS Code (Copilot)

​Claude Code

​Available Tools

​Portfolio & Holdings

​Transactions

​Historical & Snapshots

​Metadata

​Specialized

​Virtual Users

​Address Book

​Bundles

​Example Prompts

​Error Handling

​Resources

GitHub

API Docs

Pricing

Features

Installation

Configuration

Claude Desktop

Cursor

VS Code (Copilot)

Claude Code

Available Tools

Portfolio & Holdings

Transactions

Historical & Snapshots

Metadata

Specialized

Virtual Users

Address Book

Bundles

Example Prompts

Error Handling

Resources