Haiku MCP Server

An MCP (Model Context Protocol) server that enables AI agents to execute blockchain transactions via the Haiku API.

npm version

Features

• Token Discovery: List supported tokens and DeFi assets across 21 blockchain networks
• Balance Checking: Get wallet balances across all supported chains
• Trading Quotes: Get quotes for swaps and portfolio rebalancing
• Transaction Building: Convert quotes to unsigned EVM transactions
• Wallet Integration: Extract EIP-712 payloads for external wallet signing (Coinbase, AgentKit, Safe, etc.)
• Self-Contained Execution: Optional end-to-end execution with WALLET_PRIVATE_KEY env var
• Yield Discovery: Find the highest-yielding DeFi opportunities across protocols and chains, filtered by APY, TVL, and category
• Portfolio Analysis: Analyze a wallet's holdings and surface context-specific yield opportunities based on what it actually holds

Installation

npm install haiku-mcp-server

Or run directly with npx:

npx haiku-mcp-server

Configuration

Environment Variables

Note: The API works without a key, but providing one unlocks higher rate limits for production use.

Claude Desktop Configuration

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "haiku": {
      "command": "npx",
      "args": ["haiku-mcp-server"]
    }
  }
}

With API key for higher rate limits:

{
  "mcpServers": {
    "haiku": {
      "command": "npx",
      "args": ["haiku-mcp-server"],
      "env": {
        "HAIKU_API_KEY": "your-api-key-here"
      }
    }
  }
}

Available Tools

haiku_get_tokens

Get supported tokens and DeFi assets for trading.

Parameters:

• network (optional): Filter by chain ID (e.g., 42161 for Arbitrum)
• category (optional): Filter by token category:
  • token - Vanilla tokens (ETH, USDC, etc.)
  • collateral - eg. Aave aTokens (deposited collateral)
  • varDebt - eg. Aave variable debt tokens
  • vault - eg. Yearn/Morpho yield vaults
  • weightedLiquidity - eg. Balancer LP tokens
  • concentratedLiquidity - eg. Uniswap V3 LP positions

Example:

{
  "network": 42161,
  "category": "token"
}

haiku_get_balances

Get token balances for a wallet address across all chains.

Parameters:

• walletAddress (optional): Wallet address or ENS name. Required when WALLET_PRIVATE_KEY is not set; omit to auto-derive from WALLET_PRIVATE_KEY when it is set.

Example:

{
  "walletAddress": "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045"
}

Omit walletAddress when WALLET_PRIVATE_KEY is set to use the derived address.

haiku_get_quote

Get a quote for a token swap or portfolio rebalance.

Note: Quotes are valid for 5 minutes, but execute as quickly as possible after quoting — the longer you wait, the more likely prices have moved and the transaction will fail on-chain.

Parameters:

• inputPositions (required): Map of token IID to amount to spend
• targetWeights (required): Map of output token IID to weight (must sum to 1)
• slippage (optional): Max slippage as decimal (default: 0.003)
• receiver: Receiving wallet address. Required when WALLET_PRIVATE_KEY is not set — must be provided explicitly. When WALLET_PRIVATE_KEY is set, auto-derived if omitted. When WALLET_PRIVATE_KEY is not set (Path B), you must pass receiver explicitly.

Example:

{
  "inputPositions": {
    "arb:0x82aF49447D8a07e3bd95BD0d56f35241523fBab1": "1.0"
  },
  "targetWeights": {
    "arb:0xaf88d065e77c8cC2239327C5EDb3A432268e5831": 0.5,
    "arb:0xFd086bC7CD5C481DCC9C85ebE478A1C0b69FCbb9": 0.5
  },
  "slippage": 0.005
}

Example above omits receiver (valid when WALLET_PRIVATE_KEY is set). For Path B, include "receiver": "0x...".

haiku_prepare_signatures

Extract and normalize EIP-712 signing payloads from a quote for external wallet signing (Path B only). When using quoteId, the quote must have been obtained in the same session.

Use this when a wallet MCP handles signing (Coinbase Payments MCP, wallet-agent, AgentKit, Safe, etc.). Returns standardized typed data that any wallet's signTypedData can consume, plus step-by-step instructions.

Parameters:

• quoteId (preferred): Quote ID from haiku_get_quote — server resolves the full quote from session cache. QuoteId only works when the quote was returned by haiku_get_quote in the same MCP session; otherwise use quoteResponse.
• quoteResponse (fallback): Full response object from haiku_get_quote, if quoteId is unavailable

Returns:

• requiresPermit2: Whether Permit2 signature is needed
• permit2: EIP-712 payload to pass to signTypedData (if required)
• requiresBridgeSignature: Whether bridge signature is needed
• bridgeIntent: EIP-712 payload to pass to signTypedData (if required)
• sourceChainId: Chain ID for the transaction
• instructions: Step-by-step instructions for completing the flow

Example:

{
  "quoteId": "abc123..."
}

haiku_discover_yields

Discover yield-bearing opportunities across DeFi protocols, ranked by APY or TVL.

Use this to answer questions like "best lending yields on Arbitrum", "highest APY vaults with at least $1M TVL", or "what can I do with USDC on Base". The iid field in results can be used directly as a key in the targetWeights object in haiku_get_quote.

Parameters:

• network (optional): Filter by chain ID (e.g., 42161 for Arbitrum)
• category (optional): lending (Aave collateral), vault (Yearn/Morpho), lp (Balancer/Uniswap), all (default)
• minApy (optional): Minimum APY as a percentage (e.g., 5 means ≥5% APY)
• minTvl (optional): Minimum TVL in USD (e.g., 1000000 means ≥$1M). Filters to established mainstream vaults.
• sortBy (optional): apy (default) or tvl, descending
• limit (optional): Max results (default 20)

Example:

{
  "network": 42161,
  "category": "lending",
  "minTvl": 1000000,
  "sortBy": "apy",
  "limit": 10
}

haiku_analyze_portfolio

Analyze a wallet's DeFi portfolio and surface relevant yield opportunities.

Returns current positions enriched with available APY options, collateral health factors, and context-specific opportunities based on what the wallet actually holds. Pair with haiku_discover_yields for broader market context, then use haiku_get_quote to execute.

Parameters:

• walletAddress (required): Wallet address (0x...) to analyze

Example:

{
  "walletAddress": "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045"
}

haiku_execute

Execute a quote. Two distinct paths depending on who holds the private key.

Path A — Self-contained (WALLET_PRIVATE_KEY set in env): Haiku signs Permit2/bridge payloads internally and broadcasts. Returns a tx hash.

Parameters:

• quoteId (required): Quote ID from haiku_get_quote
• sourceChainId (recommended): Chain ID from the quote response. Omit only if the quote was obtained in the same session — the server can recover from cache.
• permit2SigningPayload (optional): Pass through from haiku_get_quote if present
• bridgeSigningPayload (optional): Pass through from haiku_get_quote if present (cross-chain only)
• approvals (optional): Pass through from haiku_get_quote if present

Example:

{
  "quoteId": "abc123...",
  "sourceChainId": 42161,
  "permit2SigningPayload": { /* from haiku_get_quote, if present */ },
  "approvals": [ /* from haiku_get_quote, if present */ ]
}

Path B — External wallet (no WALLET_PRIVATE_KEY, using a wallet MCP): You sign and broadcast. broadcast: false is required — without WALLET_PRIVATE_KEY, haiku cannot sign or send the final EVM transaction. If you call haiku_execute with broadcast: true and no WALLET_PRIVATE_KEY, the server returns an error directing you to set broadcast: false and broadcast the returned transaction via your wallet MCP.

Before calling haiku_execute:

1. If approvals is non-empty in the quote: broadcast each approval as a transaction { to, data, value } (include value when present, e.g. for native token) via your wallet MCP and wait for confirmation.
2. If signatures are required: call haiku_prepare_signatures with the quoteId, sign the returned EIP-712 payloads via your wallet MCP, then pass the signatures here.

Parameters:

• quoteId (required): Quote ID from haiku_get_quote
• sourceChainId (recommended): Chain ID from the quote response. Omit only if the quote was obtained in the same session — the server can recover from cache.
• broadcast (required): Must be false — haiku returns the unsigned tx for you to broadcast
• permit2Signature (optional): Signature from signing the Permit2 payload via your wallet MCP
• userSignature (optional): Signature from signing the bridge payload via your wallet MCP (cross-chain only)

Example:

{
  "quoteId": "abc123...",
  "sourceChainId": 42161,
  "broadcast": false,
  "permit2Signature": "0x..."
}

Returns { transaction: { to, data, value, chainId } } — pass transaction to your wallet MCP's sendTransaction.

Token IID Format

Tokens are identified using the IID format: chainSlug:tokenAddress

Examples:

• arb:0x82aF49447D8a07e3bd95BD0d56f35241523fBab1 - WETH on Arbitrum
• arb:0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee - Native ETH on Arbitrum
• base:0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913 - USDC on Base

Supported Chains

Workflow Examples

Path A: Self-Contained Swap (WALLET_PRIVATE_KEY set)

Haiku handles all signing and broadcasting. Returns a tx hash.

1. haiku_get_quote(inputPositions, targetWeights) → returns quoteId, sourceChainId, permit2SigningPayload?, bridgeSigningPayload?, approvals
2. haiku_execute(quoteId, sourceChainId, permit2SigningPayload?, bridgeSigningPayload?, approvals)
   → Haiku broadcasts approvals, signs Permit2/bridge internally, broadcasts swap, returns tx hash

Path B: External Wallet (wallet MCP handles signing + broadcasting)

Use when WALLET_PRIVATE_KEY is not set and a separate wallet MCP holds the keys.

Simple swap (no Permit2 or bridge signatures needed, e.g. native ETH input):

1. haiku_get_quote(inputPositions, targetWeights, receiver) → returns quoteId, sourceChainId, approvals
2. For each item in approvals: broadcast as transaction { to, data, value } (include value when present) via wallet MCP and wait for confirmation
3. haiku_execute(quoteId, sourceChainId, broadcast: false)
   → returns { transaction: { to, data, value, chainId } }
4. Broadcast transaction via wallet MCP

With Permit2 or bridge signatures (e.g. ERC-20 input or cross-chain swap):

1. haiku_get_quote(inputPositions, targetWeights, receiver) → returns quoteId, sourceChainId, approvals, permit2SigningPayload?, bridgeSigningPayload?
2. For each item in approvals: broadcast as transaction { to, data, value } (include value when present) via wallet MCP and wait for confirmation
3. haiku_prepare_signatures(quoteId) → returns normalized EIP-712 payloads + step-by-step instructions
4. Sign payloads via wallet MCP (e.g. coinbase_sign_typed_data) → get permit2Signature?, userSignature?
5. haiku_execute(quoteId, sourceChainId, permit2Signature?, userSignature?, broadcast: false)
   → returns { transaction: { to, data, value, chainId } }
6. Broadcast transaction via wallet MCP (e.g. coinbase_send_transaction)

Yield Discovery

1. haiku_discover_yields with category/network/minTvl filters → find opportunities, note iid
2. haiku_get_quote with the chosen iid as a key in targetWeights
3. Execute via Path A or Path B above

Portfolio Analysis & Optimization

1. haiku_analyze_portfolio with wallet address → review positions and opportunities
2. Optionally haiku_discover_yields for broader market context
3. haiku_get_quote to rebalance into higher-yielding positions
4. Execute via Path A or Path B above

Transaction Signing

Two modes depending on your setup:

Self-contained (WALLET_PRIVATE_KEY set): haiku_execute signs everything internally and broadcasts. Returns a tx hash. No external signing needed.

External wallet (no WALLET_PRIVATE_KEY): Use haiku_execute with broadcast: false (required — haiku cannot sign or broadcast without the private key). If you call haiku_execute with broadcast: true and no WALLET_PRIVATE_KEY, the server returns an error directing you to set broadcast: false and broadcast the returned transaction via your wallet MCP. Returns { transaction: { to, data, value, chainId } } for your wallet MCP to broadcast. If Permit2 or bridge signatures are required, call haiku_prepare_signatures first. If approvals are present in the quote, broadcast each approval { to, data, value } (include value when present, e.g. for native token) via your wallet MCP before calling haiku_execute.

The external wallet design allows agents to use any signing infrastructure (wallet MCPs, hardware wallets, custodial services, MPC, etc.).

Cross-Chain Bridge Signatures

For cross-chain swaps, the quote may return isComplexBridge: true, indicating a bridge intent signature is required in addition to (or instead of) Permit2.

Self-contained (Path A): Pass bridgeSigningPayload from the quote to haiku_execute — it handles the bridge signature internally.

External wallet (Path B): Call haiku_prepare_signatures with the quoteId — it returns a normalized bridgeIntent EIP-712 payload. Sign it via your wallet MCP and pass the result as userSignature to haiku_execute.

Transport Modes

Stdio (default)

Standard MCP stdio transport — used by Claude Desktop, Cursor, etc.

npx haiku-mcp-server

Streamable HTTP

HTTP transport for remote hosting, Smithery, and web-based MCP clients.

npx haiku-mcp-server --http
npx haiku-mcp-server --http --port=8080

Endpoints:

• POST /mcp — MCP Streamable HTTP endpoint
• GET /health — Health check

Development

# Install dependencies
npm install

# Build
npm run build

# Run locally (stdio, works without API key)
npm start

# Run locally (HTTP)
npm run start:http

# Run with API key for higher rate limits
HAIKU_API_KEY=your-key npm start

License

MIT