Skip to main content
Glama
Octav API MCP Server

Octav API MCP Server

Official
by Octav-Labs
 ██████╗  ██████╗████████╗ █████╗ ██╗   ██╗
██╔═══██╗██╔════╝╚══██╔══╝██╔══██╗██║   ██║
██║   ██║██║        ██║   ███████║██║   ██║
██║   ██║██║        ██║   ██╔══██║╚██╗ ██╔╝
╚██████╔╝╚██████╗   ██║   ██║  ██║ ╚████╔╝
 ╚═════╝  ╚═════╝   ╚═╝   ╚═╝  ╚═╝  ╚═══╝

Octav API MCP Server

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.

Features

  • 🔗 20+ Blockchain Support: Ethereum, Solana, Arbitrum, Base, Polygon, and more

  • 💼 Complete Portfolio Tracking: Wallets + DeFi protocol positions

  • 📊 Transaction History: Advanced filtering and pagination

  • 💰 Multi-Currency NAV: USD, EUR, CAD, AED, CHF, SGD, ETH, SOL, cbBTC, EURC, BNB, WHYPE

  • 📸 Historical Snapshots: Track portfolio value over time

  • 🎯 Token Distribution: Aggregated token holdings across chains

  • 🎁 Airdrop Tracking: Solana airdrop eligibility

  • 📈 Polymarket Positions: Prediction market tracking

  • 🧱 Portfolio at Block: Portfolio valued at a specific historical block

  • 🔐 Token Approvals: ERC-20 allowances granted to spender contracts

  • 📒 Address Book & Bundles: Manage saved addresses and named groups of them

Related MCP server: CoinStats MCP Server

Installation

For End Users

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-mcp

Or install globally:

npm install -g octav-api-mcp
# or
pnpm add -g octav-api-mcp

For Development

Clone the repository and build from source:

git clone https://github.com/Octav-Labs/octav-api-mcp.git
cd octav-api-mcp
pnpm install
pnpm build

Configuration

Create a .env file in the project root:

OCTAV_API_KEY=your-api-key-here

Get your API key from octav.fi.

Usage

With Claude Desktop

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"
      }
    }
  }
}

With MCP Inspector

For testing and debugging:

pnpm build
pnpm dlx @modelcontextprotocol/inspector node build/index.js

Available Tools

All tools use the octav_ prefix for namespace clarity.

Portfolio & Holdings (5 tools)

1. octav_get_portfolio

Get complete portfolio including wallet holdings and DeFi protocol positions.

Parameters:

  • addresses (required): Array with one wallet address (the API takes one address per call)

  • waitForSync (optional): Wait for a fresh sync when cached data is stale. Default: true

  • includeExplorerUrls (optional): Include blockchain explorer URLs. Default: false

Cost: 1 credit per address

2. octav_get_wallet

Get wallet holdings only (excludes DeFi protocols).

Parameters:

  • addresses (required): Array with one wallet address (the API takes one address per call)

Cost: 1 credit per address

3. octav_get_nav

Get total net worth (NAV) in specified currency.

Parameters:

  • addresses (required): Array of wallet addresses (max 50)

  • currency (optional): USD, EUR, CAD, AED, CHF, SGD, ETH, SOL, cbBTC, EURC, BNB or WHYPE (case-sensitive). Default: USD

Cost: 1 credit per address

4. octav_get_token_overview

Get aggregated token distribution across all chains.

Parameters:

  • addresses (required): Array with one wallet address (the API takes one address per call)

Cost: 1 credit per address

5. octav_get_portfolio_at_block

Get a single EVM address's portfolio valued at a specific block. Requires the Portfolio at Block add-on.

Parameters:

  • address (required): EVM wallet address

  • chain (required): ethereum, linea or monad

  • block (required): Block number

Cost: 1 credit (plus the add-on)

Transactions (2 tools)

6. octav_get_transactions

Query transaction history with filtering and pagination.

Parameters:

  • addresses (required): Array with one wallet address (the API takes one address per call)

  • 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-separated

  • interactingAddresses (optional): Array of counterparty addresses to filter by

  • search (optional): Full-text search over token symbols, names and addresses

  • tokenId (optional): NFT token ID

  • startDate (optional): Start date (YYYY-MM-DD)

  • endDate (optional): End date (YYYY-MM-DD)

  • sort (optional): NEWEST or OLDEST by timestamp. Default: NEWEST

  • hideSpam (optional): Exclude spam transactions

  • hideDust (optional): Exclude dust transactions

  • offset (optional): Pagination offset. Default: 0

  • limit (optional): Number of results (1-250). Default: 50

Cost: 1 credit per address

7. octav_sync_transactions

Manually trigger transaction synchronization.

Parameters:

  • addresses (required): Array with one wallet address (the API takes one address per call)

Cost: 1 credit, plus 1 credit per 250 transactions indexed

Historical & Snapshots (2 tools)

8. octav_get_historical

Get portfolio snapshot for a specific date in the past.

Parameters:

  • addresses (required): Array with one wallet address (the API takes one address per call)

  • date (required): Date for snapshot (YYYY-MM-DD)

Cost: 1 credit per address

9. octav_subscribe_snapshot

Subscribe to automatic portfolio snapshots.

Parameters:

  • addresses (required): Array of wallet addresses

  • frequency (required): Snapshot frequency (daily, weekly, monthly)

Cost: 1 credit per address

Metadata (5 tools)

10. octav_get_status

Check synchronization status across all chains.

Parameters:

  • addresses (required): Array with one wallet address (the API takes one address per call)

Cost: FREE

11. octav_get_credits

Check API credit balance and usage.

Parameters: None

Cost: FREE

12. octav_get_chains

List 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

13. octav_get_chain_protocols

List the protocols tracked on a chain, with the keys used by the protocol filter of octav_get_transactions.

Parameters:

  • chain (required): Chain key

  • page (optional): Page number. Default: 1

  • limit (optional): Protocols per page (1-100). Default: 20

Cost: FREE

14. octav_get_contract_protocol

Identify 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

Specialized (3 tools)

15. octav_get_airdrop

Check airdrop eligibility (Solana only).

Parameters:

  • address (required): Solana wallet address

Cost: 1 credit

16. octav_get_polymarket

Get Polymarket prediction market positions.

Parameters:

  • address (required): Polymarket (proxy) wallet address, as shown on the Polymarket profile. It is read as-is; a regular wallet's proxy is not looked up

Cost: 1 credit

17. octav_get_approvals

Get the ERC-20 token approvals a wallet has granted on one chain. Paginated by cursor.

Parameters:

  • address (required): EVM wallet address

  • chain (required): arbitrum, avalanche, base, binance, ethereum, gnosis, linea, optimism or polygon

  • limit (optional): Approvals per page (1-100). Default: 25

  • cursor (optional): Cursor from the previous page

Cost: 1 credit

Virtual Users (2 tools)

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

18. octav_list_virtual_users

List the account's virtual users with their virtual:<id> addresses.

Parameters: None

Cost: 1 credit

19. octav_get_virtual_users_portfolio

Get portfolios for virtual users.

Parameters:

  • addresses (required): Array of virtual:<id> addresses (max 50)

  • aggregated (optional): Return one combined portfolio. Default: false

  • waitForSync (optional): Wait for a fresh sync when cached data is stale. Default: true

  • includeExplorerUrls (optional): Include blockchain explorer URLs. Default: false

Cost: 1 credit per address

Address Book (4 tools)

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.

20. octav_list_address_book

List every saved address with its label, plan, plan expiry, and paid status.

Parameters: None

Cost: 1 credit

21. octav_add_address_book_entries

Save 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

22. octav_rename_address_book_entry

Change the label on a saved address.

Parameters:

  • address (required): Address of the entry

  • label (required): New label, up to 255 characters. An empty string clears it.

  • confirm (required): Must be true, since this replaces the current label

Cost: 1 credit

23. 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.

Parameters:

  • address (required): Address of the entry

  • confirm (required): Must be true

Cost: 1 credit

Bundles (7 tools)

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.

24. octav_list_bundles

List every bundle with its id, name, and addresses.

Parameters: None

Cost: 1 credit

25. octav_get_bundle

Get one bundle by id.

Parameters:

  • bundleId (required): Bundle id

Cost: 1 credit

26. octav_create_bundle

Create a bundle. Names must be unique, and no two bundles may hold exactly the same addresses.

Parameters:

  • name (required): Bundle name, 1-255 characters

  • addresses (required): Array of addresses already in the address book

Cost: 1 credit

27. octav_rename_bundle

Rename a bundle.

Parameters:

  • bundleId (required): Bundle id

  • name (required): New name, 1-255 characters

  • confirm (required): Must be true, since this replaces the current name

Cost: 1 credit

28. octav_delete_bundle

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

Parameters:

  • bundleId (required): Bundle id

  • confirm (required): Must be true

Cost: 1 credit

29. octav_add_bundle_address

Add an address from the address book to a bundle.

Parameters:

  • bundleId (required): Bundle id

  • address (required): Address to add

Cost: 1 credit

30. 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.

Parameters:

  • bundleId (required): Bundle id

  • address (required): Address to remove

  • confirm (required): Must be true

Cost: 1 credit

Address Formats

The server accepts two address formats:

  • EVM addresses: 0x followed by 40 hex characters (Ethereum, Polygon, Arbitrum, Base, etc.)

  • Solana addresses: 32-44 character base58 strings

The address book and bundle tools also accept Starknet and Tron addresses.

Response Format

All tools return the Octav API response as JSON.

API Costs & Rate Limits

  • Most endpoints cost 1 credit per address

  • octav_get_status, octav_get_credits, octav_get_chains and octav_get_chain_protocols are FREE

  • octav_get_contract_protocol costs 5 credits, refunded if no protocol is found

  • Transaction queries have a max limit of 250 per request

  • Max 10 addresses per request

  • Purchase credits at octav.fi

Error Handling

The server provides clear error messages for:

  • Validation errors: Invalid address formats, parameter constraints

  • Authentication errors: Invalid API key

  • Insufficient credits: Low balance with purchase link

  • Rate limiting: Retry suggestions

  • Network errors: Connection issues

Development

Build

pnpm build

Watch Mode

pnpm dev

Testing

pnpm test

Example Usage

Once configured with Claude Desktop, you can ask questions like:

  • "What's in my Ethereum wallet 0x..."

  • "Show me my complete crypto portfolio for addresses X, Y, Z"

  • "What was my net worth on 2024-01-01?"

  • "Get my transaction history for the last month"

  • "Am I eligible for any Solana airdrops?"

  • "What are my Polymarket positions?"

  • "Which contracts can spend my tokens on Ethereum?"

  • "What was 0x... worth at Ethereum block 19000000?"

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

Supported Chains

Ethereum, Solana, Arbitrum, Base, Polygon, Optimism, BNB Chain, Avalanche, Fantom, Cronos, Gnosis, Celo, Moonbeam, Moonriver, Harmony, Aurora, Metis, Boba, Fuse, Evmos, Kava, and more.

License

MIT

Support

For API issues or questions, visit octav.fi or check the API documentation.

Available Tools

30 tools
octav_add_address_book_entriesAdd Address Book EntriesA

Save addresses (EVM, Solana, Starknet, or Tron) to the address book, each with an optional label. An address already in the book keeps its existing label; use octav_rename_address_book_entry to change it. Accounts without a paid plan can save up to 50 addresses. Returns the full address book. Costs 1 credit.

Inputs: entries (required).

octav_add_bundle_addressAdd Address to BundleA

Add one address to a bundle. The address must already be in the address book. Returns the updated bundle. Costs 1 credit.

Inputs: address (required), bundleId (required).

octav_create_bundleCreate BundleA

Create a named bundle from addresses that are already in the address book (save them first with octav_add_address_book_entries). Names must be unique (case-sensitive), a bundle cannot be empty, and no two bundles may hold exactly the same addresses. Default limits are 5 bundles and 10 addresses per bundle. Bundles created through the API are private. Costs 1 credit.

Inputs: name (required), addresses (required).

octav_delete_bundleDelete BundleA
Destructive

Delete a bundle. Its addresses stay in the address book. Requires confirm: true. Costs 1 credit.

Inputs: bundleId (required), confirm.

octav_get_airdropGet Airdrop EligibilityA
Read-only

Check airdrop eligibility for Solana address. Shows eligible airdrops with claim links. Solana addresses only. Costs 1 credit.

Inputs: address (required).

octav_get_approvalsGet Token ApprovalsA
Read-only

Get the ERC-20 token approvals (allowances) a wallet has granted to spender contracts on one chain. Paginated: pass the returned cursor to get the next page; there are no more pages when it is absent or null. Costs 1 credit.

Inputs: chain (required), address (required), limit, cursor.

octav_get_bundleGet BundleA
Read-only

Get one bundle by id, with its name and addresses. Use octav_list_bundles to find bundle ids. Costs 1 credit.

Inputs: bundleId (required).

octav_get_chain_protocolsGet Chain ProtocolsA
Read-only

List the DeFi protocols Octav tracks on a chain, with their keys (used by the protocol filter on octav_get_transactions). Paginated; the response says whether more pages exist. FREE - no credits required.

Inputs: chain (required), page, limit.

octav_get_chainsGet Supported ChainsA
Read-only

List every chain Octav supports, with its key (used by chain filters in other tools), name, chain id, and whether portfolio and transactions are supported. FREE - no credits required.

Inputs: no named parameters.

octav_get_contract_protocolGet Contract ProtocolA
Read-only

Identify the DeFi protocol a contract address belongs to, such as a spender from octav_get_approvals or a transaction counterparty. With a chain it returns { protocol }; without one it returns { protocols } for every chain the address is known on. Costs 5 credits, refunded if no protocol is found.

Inputs: contract (required), chain.

octav_get_creditsGet Credit BalanceA
Read-only

Check API credit balance, usage, and remaining credits. FREE - no credits required.

Inputs: no named parameters.

octav_get_historicalGet Historical PortfolioA
Read-only

Get portfolio snapshot for a specific date in the past. Shows holdings and values at that point in time. Costs 1 credit per address.

Inputs: date (required), addresses (required).

octav_get_navGet Net Asset ValueA
Read-only

Get total net worth (NAV) in specified currency. Supports USD, EUR, CAD, AED, CHF, SGD, ETH, SOL, cbBTC, EURC, BNB, WHYPE. Costs 1 credit per address.

Inputs: addresses (required), currency.

octav_get_polymarketGet Polymarket PositionsA
Read-only

Get the Polymarket prediction market positions and collateral of a Polymarket (proxy) wallet. Pass the proxy wallet itself, as shown on the Polymarket profile; a regular wallet's proxy is not looked up. Costs 1 credit.

Inputs: address (required).

octav_get_portfolioGet Full PortfolioA
Read-only

Get complete portfolio including wallet holdings and DeFi protocol positions across 20+ blockchains. Returns token balances, values, and protocol positions. Waits for a fresh sync by default. Costs 1 credit per address.

Inputs: addresses (required), waitForSync, includeExplorerUrls.

octav_get_portfolio_at_blockGet Portfolio at BlockA
Read-only

Get a single EVM address's portfolio valued at a specific block on ethereum, linea or monad, with every balance and price as of that block. Requires the Portfolio at Block add-on. Costs 1 credit.

Inputs: block (required), chain (required), address (required).

octav_get_statusGet Sync StatusA
Read-only

Check synchronization status of addresses across all chains. Shows which chains are synced and last sync time. FREE - no credits required.

Inputs: addresses (required).

octav_get_token_overviewGet Token DistributionA
Read-only

Get aggregated token distribution across all chains. Shows which tokens you hold, their values, and percentage breakdown. Costs 1 credit per address.

Inputs: date (required), addresses (required).

octav_get_transactionsGet Transaction HistoryB
Read-only

Query transaction history with filtering and pagination. Filter by chain, type, protocol, counterparty, text search, NFT token ID, and date range, and hide spam or dust. Max 250 transactions per request. Costs 1 credit per address.

Inputs: addresses (required), sort, type, chain, +10 more.

octav_get_virtual_users_portfolioGet Virtual Users PortfolioA
Read-only

Get portfolios for virtual users, using the virtual: addresses from octav_list_virtual_users. Same shape as octav_get_portfolio; set aggregated for one combined portfolio. Waits for a fresh sync by default. Requires Pro. Costs 1 credit per address.

Inputs: addresses (required), aggregated, waitForSync, includeExplorerUrls.

octav_get_walletGet Wallet HoldingsA
Read-only

Get wallet holdings only (excludes DeFi protocols). Returns token balances and values across all chains. Costs 1 credit per address.

Inputs: addresses (required).

octav_list_address_bookList Address BookA
Read-only

List every address saved in the account address book (the same list shown in Octav Pro), with its label, plan (FREE, LITE, PRO), plan expiry, and whether the plan is paid. Costs 1 credit.

Inputs: no named parameters.

octav_list_bundlesList BundlesA
Read-only

List every bundle (a named group of address book addresses, as in Octav Pro) with its id, name, and addresses. Pass a bundle's addresses to octav_get_portfolio to see its holdings. Costs 1 credit.

Inputs: no named parameters.

octav_list_virtual_usersList Virtual UsersA
Read-only

List the virtual users on the account (balance-tracking or CEX-linked accounts managed in Octav Pro), with their virtual: address, type, and label. Requires Pro. Costs 1 credit.

Inputs: no named parameters.

octav_remove_address_book_entryRemove Address Book EntryA
Destructive

Remove an address from the address book. Entries on a paid plan or authorized by the wallet owner cannot be removed through the API; they must be removed in Octav Pro. Requires confirm: true. Costs 1 credit.

Inputs: address (required), confirm.

octav_remove_bundle_addressRemove Address from BundleA
Destructive

Remove one address from a bundle; it stays in the address book. A bundle cannot be emptied, so to remove its last address delete the bundle instead. Requires confirm: true. Returns the updated bundle. Costs 1 credit.

Inputs: address (required), bundleId (required), confirm.

octav_rename_address_book_entryRename Address Book EntryA
Destructive

Change the label on an address already in the address book, replacing the current one. Pass an empty string to clear the label. Requires confirm: true. Costs 1 credit.

Inputs: label (required), address (required), confirm.

octav_rename_bundleRename BundleA
Destructive

Rename a bundle, replacing its current name. Names must be unique (case-sensitive). Requires confirm: true. Costs 1 credit.

Inputs: name (required), bundleId (required), confirm.

octav_subscribe_snapshotSubscribe to SnapshotsA

Subscribe to automatic portfolio snapshots. Enables historical tracking. Costs 1200 credits. API expects addresses with optional descriptions.

Inputs: addresses (required), description.

octav_sync_transactionsSync TransactionsA

Manually trigger transaction synchronization for one address. Forces immediate indexing of latest transactions. Costs 1 credit, plus 1 credit per 250 transactions indexed.

Inputs: addresses (required).

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.9/5.0

    Scored across 30 tools

    Disambiguation4/5

    Most tools target clearly distinct resources (transactions, approvals, chains, credits, address book, bundles, virtual users) and the descriptions do real work separating them. The weak spot is a cluster of five portfolio-valued reads — get_portfolio, get_wallet, get_nav, get_token_overview, get_historical, get_portfolio_at_block — which an agent could easily mix up despite the distinctions being spelled out.

    Naming Consistency5/5

    Every tool uses the same octav_verb_noun snake_case pattern with a small, predictable verb set (get, list, create, add, remove, rename, delete, sync, subscribe). Sub-resources like address_book_entry and bundle_address are named consistently across their CRUD families.

    Tool Count3/5

    30 tools is heavy and sits at the upper bound; the surface splits into many small families (address book CRUD, bundle CRUD, virtual users, metadata, credits, prediction markets). Each tool is defensible individually, but the aggregate is sprawling and the portfolio-read variants inflate the count.

    Completeness4/5

    Coverage is broad: portfolio/holdings, historical snapshots, transactions plus sync, approvals, chains and protocols, credits, and full CRUD for both address book entries and bundles. Minor gaps remain, such as single-transaction detail or per-token lookups, but agents can work around them via the existing list and filter endpoints.

    Maintenance

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers