Skip to main content
Glama
Octav API MCP Server

Octav API MCP Server

Official
by Octav-Labs
README.md
```bash
 ██████╗  ██████╗████████╗ █████╗ ██╗   ██╗
██╔═══██╗██╔════╝╚══██╔══╝██╔══██╗██║   ██║
██║   ██║██║        ██║   ███████║██║   ██║
██║   ██║██║        ██║   ██╔══██║╚██╗ ██╔╝
╚██████╔╝╚██████╗   ██║   ██║  ██║ ╚████╔╝
 ╚═════╝  ╚═════╝   ╚═╝   ╚═╝  ╚═╝  ╚═══╝
```
# Octav API MCP Server

MCP (Model Context Protocol) server for the [Octav](https://octav.fi) 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

## 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):

```bash
npx octav-api-mcp
```

Or install globally:

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

### For Development

Clone the repository and build from source:

```bash
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:

```bash
OCTAV_API_KEY=your-api-key-here
```

Get your API key from [octav.fi](https://octav.fi/api).

## Usage

### With Claude Desktop

Add to your Claude Desktop configuration (`~/Library/Application Support/Claude/claude_desktop_config.json` on macOS):

```json
{
  "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):**

```json
{
  "mcpServers": {
    "octav": {
      "command": "octav-api-mcp",
      "env": {
        "OCTAV_API_KEY": "your-api-key-here"
      }
    }
  }
}
```

### With MCP Inspector

For testing and debugging:

```bash
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](https://pro.octav.fi), 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](https://pro.octav.fi). 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](https://github.com/Octav-Labs/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](https://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

```bash
pnpm build
```

### Watch Mode

```bash
pnpm dev
```

### Testing

```bash
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

## Links

- [Octav Website](https://octav.fi)
- [Octav API Documentation](https://docs.octav.fi)
- [Model Context Protocol](https://modelcontextprotocol.io)

## Support

For API issues or questions, visit [octav.fi](https://octav.fi) or check the [API documentation](https://docs.octav.fi).

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