MCP Derive

A comprehensive Model Context Protocol (MCP) server for the Derive API by Lyra Finance. This server provides 31+ tools to access real-time market data, historical data, trading capabilities, and account management for options, perpetuals, and spot trading.

Features

Real-time Market Data (Low Latency)

• get_ticker - Real-time prices, bid/ask, volume, Greeks for single instruments
• get_tickers - Multi-instrument ticker data efficiently
• get_orderbook - Order book with configurable depth and spread analysis
• get_currencies - All available trading pairs
• get_instruments - Comprehensive instrument data with fees and constraints

Tick-by-Tick Historical Data

• get_trade_history - Complete trade history with filtering and pagination
• get_funding_rate_history - Perpetual funding rates with timestamps
• get_spot_feed_history - Index price feed data
• get_option_settlement_history - Option expiration and settlement data
• get_liquidation_history - Platform liquidation events

Account Management

• get_account - Account details, subaccounts, rate limits, fees
• get_subaccounts - All subaccounts with labels
• get_balance - Total balance across subaccounts and collaterals
• get_positions - Open positions with PnL, Greeks, liquidation prices
• get_collaterals - Collateral information and valuations
• get_margin - Detailed margin metrics and status

Trading (All Instruments)

• place_order - Market or limit orders for options, perps, and spot
• cancel_order - Cancel individual orders
• cancel_all_orders - Bulk cancel with filtering
• replace_order - Atomic order replacement
• get_open_orders - All open orders
• get_orders_history - Complete order history with fills

Trade & Account History

• get_my_trades - Personal trade history with fees and PnL
• get_funding_history - Funding payments paid/received
• get_deposit_history - Deposit transactions
• get_withdrawal_history - Withdrawal transactions

RFQ (Request For Quote)

• send_rfq - Request quotes from market makers
• get_rfqs - View active RFQs
• execute_quote - Execute at quoted prices

Risk Management

• get_liquidation_price - Current liquidation price for positions
• margin_watch - Accounts approaching liquidation

Installation

git clone <repo-url> mcp-derive
cd mcp-derive
npm install

Configuration

Environment Variables

# API Environment (mainnet or testnet)
DERIVE_ENVIRONMENT=mainnet

# Ethereum wallet address
DERIVE_WALLET=0x1234567890abcdef1234567890abcdef12345678

# Private key for transaction signing (optional, needed for trading)
DERIVE_PRIVATE_KEY=0xabcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890

Setup with Claude Desktop

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

{
  "mcpServers": {
    "derive": {
      "command": "node",
      "args": ["/absolute/path/to/mcp-derive/index.js"],
      "env": {
        "DERIVE_ENVIRONMENT": "testnet",
        "DERIVE_WALLET": "0x...",
        "DERIVE_PRIVATE_KEY": "0x..."
      }
    }
  }
}

Setup with Claude Code CLI

claude mcp add derive
# When prompted:
# - Command: node
# - Arguments: /absolute/path/to/mcp-derive/index.js
# - Environment variables:
#   - DERIVE_ENVIRONMENT=testnet
#   - DERIVE_WALLET=0x...
#   - DERIVE_PRIVATE_KEY=0x...

API Endpoints

Mainnet

• HTTP: https://api.lyra.finance
• WebSocket: wss://api.lyra.finance/ws (not yet supported by MCP)

Testnet

• HTTP: https://api-demo.lyra.finance
• WebSocket: wss://api-demo.lyra.finance/ws (not yet supported by MCP)

Tool Documentation

Public Market Data Tools

get_currencies

Get all available currencies on the platform.

Usage: Get all currencies to find available trading pairs

get_instruments

Get tradeable instruments for a specific currency and type.

Parameters:
  - currency (required): BTC, ETH, SOL, etc.
  - instrument_type (required): erc20, option, perp
  - expired (optional): Include expired instruments (default: false)

Response: Array of instruments with:
  - Fees (maker/taker rates)
  - Price constraints (min/max amounts, tick size)
  - For options: Strike, expiry, Greeks
  - For perps: Funding rate, interest rates

get_ticker

Real-time ticker for a single instrument.

Parameters:
  - instrument_name (required): e.g., BTC-PERP, ETH-20250131-3000-C

Response:
  - Best bid/ask with amounts
  - Last price, 24h volume, open interest
  - Greeks (for options): delta, gamma, vega, theta, rho
  - Mark price vs index price

get_tickers

Get tickers for multiple instruments (more efficient than get_ticker).

Parameters:
  - currency (optional): Filter by currency
  - instrument_type (optional): erc20, option, or perp

get_orderbook

Real-time order book with depth and spread analysis.

Parameters:
  - instrument_name (required): Instrument to get book for
  - depth (optional): Number of price levels (default 10, max 100)

Response:
  - Bid side: prices, amounts, cumulative
  - Ask side: prices, amounts, cumulative
  - Spread and mid-price

Historical Data Tools

get_trade_history

Tick-by-tick trade history across the platform.

Parameters:
  - instrument_name (optional): Filter by instrument
  - currency (optional): Filter by currency
  - instrument_type (optional): erc20, option, perp
  - from_timestamp (optional): Start time (ms)
  - to_timestamp (optional): End time (ms)
  - page (optional): Page number (default 1)
  - page_size (optional): Results per page (default 100, max 1000)
  - trade_id (optional): Get specific trade
  - tx_hash (optional): Get by transaction hash
  - tx_status (optional): settled, reverted, timed_out

Response: Trade details including:
  - Price, amount, side (buy/sell)
  - Buyer/seller addresses
  - Timestamp, transaction hash
  - Rebates and fees

get_funding_rate_history

Historical funding rates for perpetual contracts.

Parameters:
  - instrument_name (optional): e.g., BTC-PERP
  - currency (optional): Filter by currency
  - from_timestamp (optional): Start time
  - to_timestamp (optional): End time
  - Pagination parameters

Response: Historical funding events with:
  - Timestamp
  - Funding rate
  - Cumulative funding

get_spot_feed_history

Historical index prices (spot feeds).

Parameters:
  - currency (required): BTC, ETH, etc.
  - from_timestamp, to_timestamp: Time range
  - Pagination parameters

Response: Historical price data with timestamps

get_option_settlement_history

Option expiration and settlement data.

Response:
  - Strike price
  - Settlement price (determined at expiration)
  - Settlement timestamp
  - Option type (call/put)

get_liquidation_history

Platform-wide liquidation events.

Parameters:
  - currency (optional): Filter by currency
  - instrument_name (optional): Filter by instrument
  - Time range parameters
  - Pagination

Response: Liquidation events showing:
  - Which positions were liquidated
  - Liquidation price vs mark price
  - Amount liquidated

Account Management Tools

get_account

Account overview with rate limits and fees.

Response:
  - Subaccount IDs
  - Rate limits (TPS by operation type)
  - Fee structure
  - Account settings (cancel on disconnect, RFQ eligibility)
  - Referral code

get_subaccounts

All subaccounts for a wallet.

Response: Array of subaccounts with:
  - ID and label
  - Creation timestamp
  - Status

get_balance

Total balance across all subaccounts.

Response:
  - By collateral type (ETH, USDC, etc.)
  - Amounts and mark prices
  - Interest earned/owed
  - Margin contributions

get_positions

All open positions for a subaccount.

Parameters:
  - subaccount_id (required)
  - currency (optional): Filter
  - instrument_type (optional): erc20, option, perp

Response: Position details including:
  - Amount, entry price
  - Unrealized PnL (total and excluding fees)
  - Mark price vs index price
  - Greeks (for options)
  - Liquidation price
  - Leverage, margin requirements
  - Funding/interest accrual

get_collaterals

Collateral information for a subaccount.

Response:
  - Collateral amounts by asset
  - Mark prices and valuations
  - Interest rates (borrow/supply)
  - Margin contribution (initial and maintenance)

get_margin

Detailed margin metrics.

Response:
  - Maintenance margin required
  - Initial margin required
  - Current margin ratio
  - Available margin for new positions
  - Margin utilization status

Trading Tools

place_order

Place a new order for any instrument (options, perps, spot).

Parameters:
  - subaccount_id (required)
  - instrument_name (required): e.g., BTC-PERP, ETH-20250131-3000-C
  - side (required): buy or sell
  - amount (required): Order quantity
  - price (required for limit): Limit price
  - order_type (optional): limit (default) or market
  - reduce_only (optional): Can only reduce position (default false)
  - post_only (optional): Maker-only, no taker fills (default false)
  - label (optional): Custom order label

Response:
  - Order ID
  - Status (pending, filled, rejected)
  - Fill details if executed

cancel_order

Cancel a specific open order.

Parameters:
  - subaccount_id (required)
  - order_id (required): ID of order to cancel

cancel_all_orders

Cancel all open orders with optional filtering.

Parameters:
  - subaccount_id (required)
  - currency (optional): Only cancel this currency
  - instrument_name (optional): Only cancel this instrument

replace_order

Replace an order atomically (cancel + place in one operation).

Parameters:
  - subaccount_id (required)
  - order_id (required): Order to replace
  - amount (required): New amount
  - price (required): New price

get_open_orders

View all open orders for a subaccount.

Parameters:
  - subaccount_id (required)
  - currency (optional): Filter
  - instrument_name (optional): Filter

Response: Array of open orders with:
  - Order ID, status
  - Side, amount, price
  - Creation timestamp
  - Unfilled amount

get_orders_history

Complete order history (filled, cancelled, rejected).

Parameters:
  - subaccount_id (required)
  - currency (optional): Filter
  - instrument_name (optional): Filter
  - Pagination parameters

Account History Tools

get_my_trades

Personal trade history with P&L.

Parameters:
  - subaccount_id (required)
  - instrument_name (optional): Filter
  - currency (optional): Filter
  - Time range and pagination

Response:
  - Trade price, amount
  - Fees paid
  - Realized P&L
  - Maker/taker role
  - Timestamp, tx hash

get_funding_history

Funding payments paid and received.

Response:
  - Instrument (perpetual)
  - Funding payment amount and rate
  - P&L from funding
  - Timestamp

get_deposit_history

Deposit transactions.

Response:
  - Asset, amount
  - Transaction hash
  - Status (settled, reverted)
  - Timestamp

get_withdrawal_history

Withdrawal transactions.

Response:
  - Asset, amount
  - Transaction hash
  - Status
  - Timestamp

RFQ Tools

send_rfq

Request a quote from market makers.

Parameters:
  - subaccount_id (required)
  - instrument_name (required)
  - side (required): buy or sell
  - amount (required): Amount to quote

Response:
  - RFQ ID
  - Quotes received from different market makers
  - Best bid/ask from quotes

get_rfqs

View active RFQs and quotes.

Parameters:
  - subaccount_id (required)

Response:
  - Active RFQ requests
  - Quotes from market makers
  - Expiration times

execute_quote

Execute a market maker quote.

Parameters:
  - subaccount_id (required)
  - quote_id (required): Quote ID from RFQ

Response:
  - Execution confirmation
  - Final fill price and amount
  - Transaction hash

Risk Management Tools

get_liquidation_price

Get liquidation price for an open position.

Parameters:
  - subaccount_id (required)
  - instrument_name (required)

Response:
  - Liquidation price
  - Current mark price
  - Distance to liquidation
  - Position size

margin_watch

Accounts approaching liquidation.

Parameters:
  - wallet (optional): Wallet address

Response:
  - Subaccounts with low margin ratios
  - Current margin utilization
  - Recommended actions

Instrument Naming

Options Format

{CURRENCY}-{EXPIRY}-{STRIKE}-{TYPE}

• Example: ETH-20250131-3000-C (ETH call, Jan 31 2025, $3000 strike)
• Example: BTC-20250228-50000-P (BTC put, Feb 28 2025, $50000 strike)
• Type: C (call) or P (put)

Perpetuals Format

{CURRENCY}-PERP

• Example: BTC-PERP, ETH-PERP, SOL-PERP

Spot/ERC20 Format

{SYMBOL}

• Example: USDC, ETH, WBTC

Authentication

Public Endpoints

No authentication required. Works without any credentials.

Private Endpoints

Require:

1. DERIVE_WALLET: Your Ethereum wallet address
2. DERIVE_PRIVATE_KEY: Optional, used for signing transactions

Uses wallet-based authentication:

• X-LyraWallet: Your wallet address
• X-LyraTimestamp: Current timestamp
• X-LyraSignature: HMAC signature of timestamp

Rate Limits

Derive implements TPS (transactions per second) limits. Each account has:

• WebSocket matching TPS (for trading orders)
• WebSocket non-matching TPS (for RFQ, margin watch, etc.)
• Per-instrument limits (options, perpetuals)
• Global per-endpoint limits

Check your account's rate limits using get_account tool.

Usage Examples

Get Real-time BTC Perpetual Price

Ask Claude: "What's the current price of BTC-PERP?"

Claude will use: get_ticker(instrument_name="BTC-PERP")

View Your Positions

Ask Claude: "Show my open positions on subaccount 12345"

Claude will use: get_positions(subaccount_id=12345)

Place a Trade

Ask Claude: "Buy 0.5 BTC-PERP at $45000 on subaccount 12345"

Claude will use: place_order(
  subaccount_id=12345,
  instrument_name="BTC-PERP",
  side="buy",
  amount="0.5",
  price="45000"
)

Get Historical Trades

Ask Claude: "Show my trade history for ETH over the last 7 days"

Claude will use: get_my_trades(
  subaccount_id=12345,
  instrument_name="ETH-PERP",
  from_timestamp=<7-days-ago-ms>
)

Analyze Funding Rates

Ask Claude: "What are the funding rates for BTC and ETH perpetuals?"

Claude will use: get_funding_rate_history for both instruments

Performance & Rate Limiting

• REST API: HTTP/REST (used by this MCP) - Most stable, less likely to hit rate limits
• No WebSocket: Uses REST only (simpler, more compatible)
• Pagination: Automatic pagination support for large result sets
• Caching: Results not cached in MCP (fresh data on each call)

Rate Limiting Strategy

• Use page_size=1000 for efficient historical data fetches
• Batch related queries together
• Avoid polling the same endpoint more than once per second
• Check get_account for your specific TPS limits

Troubleshooting

"API Error" Responses

Invalid instrument name:

• Use correct format: BTC-PERP, ETH-20250131-3000-C, etc.
• Verify instrument is active using get_instruments

Authentication errors (private endpoints):

• Ensure DERIVE_WALLET environment variable is set
• Check wallet address is correct
• For trading, ensure DERIVE_PRIVATE_KEY is set
• Verify API key/credentials haven't expired

Rate limit exceeded:

• Wait before making more requests
• Check your TPS limits with get_account
• Reduce page_size or request frequency

No positions/orders found:

• Verify correct subaccount_id
• Check subaccount has active trading
• Use get_subaccounts to list available subaccounts

Network Issues

• Verify network connectivity
• Check if API is up: https://status.lyra.finance
• Confirm correct environment (mainnet vs testnet)
• Check DERIVE_ENVIRONMENT setting matches your API credentials

Additional Resources

• Derive API Documentation
• Derive Platform
• Lyra Finance
• MCP Protocol
• CCXT Derive Integration

License

MIT

Support

For issues with:

• The MCP Server: File issues in this repository
• Derive API: Check https://docs.derive.xyz or contact Derive support
• Claude Integration: Check Claude documentation

Disclaimer

This is an unofficial MCP server for Derive. Use at your own risk. Always verify trades and transactions independently. The authors are not responsible for any financial losses resulting from use of this tool.

Risk Warning: Leverage trading involves significant risk of loss. Only trade with funds you can afford to lose.