> ## Documentation Index
> Fetch the complete documentation index at: https://docs.octav.fi/llms.txt
> Use this file to discover all available pages before exploring further.

# Crypto Portfolio MCP Server

> Connect Claude, Cursor, Codex and VS Code to live crypto portfolio data through the Octav MCP server — holdings, transactions, net worth and history.

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

<Info>
  **Quick Install** — Run the MCP server with no installation required:

  ```bash theme={null}
  npx octav-api-mcp
  ```
</Info>

***

## Features

<CardGroup cols={2}>
  <Card title="Portfolio & Holdings" icon="wallet">
    Multi-chain portfolio aggregation

    * Wallet balances and DeFi positions
    * Net worth in multiple currencies
    * Token distribution overview
  </Card>

  <Card title="Transaction History" icon="receipt">
    Complete transaction records

    * Filter by chain, type, and date range
    * Manual sync triggers
    * Up to 250 results per query
  </Card>

  <Card title="Historical Snapshots" icon="clock">
    Time-series portfolio data

    * Point-in-time snapshots
    * Automatic daily subscriptions
    * Performance tracking
  </Card>

  <Card title="Specialized Data" icon="star">
    Additional capabilities

    * Solana airdrop eligibility
    * Polymarket positions
    * x402 agent payment support
  </Card>
</CardGroup>

***

## Installation

<Tabs>
  <Tab title="npx (Recommended)" icon="bolt">
    No installation required — run directly:

    ```bash theme={null}
    npx octav-api-mcp
    ```
  </Tab>

  <Tab title="npm" icon="npm">
    Install globally:

    ```bash theme={null}
    npm install -g octav-api-mcp
    ```

    Then run:

    ```bash theme={null}
    octav-api-mcp
    ```
  </Tab>

  <Tab title="pnpm" icon="box">
    Install globally:

    ```bash theme={null}
    pnpm add -g octav-api-mcp
    ```

    Then run:

    ```bash theme={null}
    octav-api-mcp
    ```
  </Tab>
</Tabs>

***

## Configuration

You'll need an Octav API key. Get one at [data.octav.fi](https://data.octav.fi/).

### Claude Desktop

<Tabs>
  <Tab title="macOS" icon="apple">
    Edit `~/Library/Application Support/Claude/claude_desktop_config.json`:

    ```json theme={null}
    {
      "mcpServers": {
        "octav": {
          "command": "npx",
          "args": ["-y", "octav-api-mcp"],
          "env": {
            "OCTAV_API_KEY": "your-api-key-here"
          }
        }
      }
    }
    ```
  </Tab>

  <Tab title="Windows" icon="windows">
    Edit `%APPDATA%\Claude\claude_desktop_config.json`:

    ```json theme={null}
    {
      "mcpServers": {
        "octav": {
          "command": "npx",
          "args": ["-y", "octav-api-mcp"],
          "env": {
            "OCTAV_API_KEY": "your-api-key-here"
          }
        }
      }
    }
    ```
  </Tab>
</Tabs>

### Cursor

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

```json theme={null}
{
  "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`:

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

### Claude Code

Add the MCP server to your project with the Claude Code CLI:

```bash theme={null}
claude mcp add octav -- npx -y octav-api-mcp
```

Then set the API key as an environment variable or pass it via your shell profile.

***

## Available Tools

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

### Portfolio & Holdings

<AccordionGroup>
  <Accordion title="octav_get_portfolio" icon="wallet">
    **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. |

    **Cost:** 1 credit per address

    ```
    "Show me the full portfolio for 0x123..."
    ```
  </Accordion>

  <Accordion title="octav_get_wallet" icon="coins">
    **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?"
    ```
  </Accordion>

  <Accordion title="octav_get_nav" icon="calculator">
    **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?"
    ```
  </Accordion>

  <Accordion title="octav_get_token_overview" icon="chart-pie">
    **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"
    ```
  </Accordion>
</AccordionGroup>

### Transactions

<AccordionGroup>
  <Accordion title="octav_get_transactions" icon="receipt">
    **Query transaction history with filtering and pagination.**

    | Parameter | Type | Required | Description |
    | - | - | - | - |
    | `addresses` | string\[] | Yes | Wallet addresses. Max 10. |
    | `chain` | string | No | Filter by chain (e.g., `ethereum`, `solana`). |
    | `type` | string | No | Filter by type (e.g., `transfer`, `swap`, `stake`). |
    | `startDate` | string | No | Start date (`YYYY-MM-DD`). |
    | `endDate` | string | No | End date (`YYYY-MM-DD`). |
    | `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..."
    ```
  </Accordion>

  <Accordion title="octav_sync_transactions" icon="arrows-rotate">
    **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..."
    ```
  </Accordion>
</AccordionGroup>

### Historical & Snapshots

<AccordionGroup>
  <Accordion title="octav_get_historical" icon="clock">
    **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?"
    ```
  </Accordion>

  <Accordion title="octav_subscribe_snapshot" icon="bell">
    **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"
    ```
  </Accordion>
</AccordionGroup>

### Metadata

<AccordionGroup>
  <Accordion title="octav_get_status" icon="circle-check">
    **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?"
    ```
  </Accordion>

  <Accordion title="octav_get_credits" icon="tag">
    **Check API credit balance and usage.**

    No parameters required.

    **Cost:** Free

    ```
    "How many API credits do I have left?"
    ```
  </Accordion>
</AccordionGroup>

### Specialized

<AccordionGroup>
  <Accordion title="octav_get_airdrop" icon="gift">
    **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"
    ```
  </Accordion>

  <Accordion title="octav_get_polymarket" icon="chart-line">
    **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..."
    ```
  </Accordion>

  <Accordion title="octav_agent_wallet" icon="robot">
    **Wallet holdings via x402 payment protocol for AI agents with automatic payment.**

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

    **Cost:** Paid via HTTP 402 payment protocol
  </Accordion>

  <Accordion title="octav_agent_portfolio" icon="robot">
    **Full portfolio via x402 payment protocol for AI agents with automatic payment.**

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

    **Cost:** Paid via HTTP 402 payment protocol
  </Accordion>
</AccordionGroup>

<Note>
  Prefer the API-key tools above. Reach for `octav_agent_*` only when the user explicitly asks for x402, or when the agent has a funded wallet and no API key. They cover only wallet, portfolio, nav, status, and chains — **transaction history is not available over x402**. See [Agent Endpoints (x402)](/api/endpoints/agent-x402).
</Note>

***

## 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"
```

```
"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 EVM or Solana format | Use `0x...` (40 hex chars) for EVM or base58 for Solana |
| 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](https://data.octav.fi/) |
| Rate limit exceeded | Too many requests per minute | Wait and retry — the server includes retry guidance |

***

## Resources

<CardGroup cols={3}>
  <Card title="GitHub" icon="github" href="https://github.com/Octav-Labs/octav-api-mcp">
    Source code and issues
  </Card>

  <Card title="API Docs" icon="book" href="/api/introduction">
    Full REST API reference
  </Card>

  <Card title="Pricing" icon="tag" href="/api/pricing">
    Credit packages and costs
  </Card>
</CardGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.