Derive MCP

# 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 ```bash git clone <repo-url> mcp-derive cd mcp-derive npm install ``` ## Configuration ### Environment Variables ```bash # 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): ```json { "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 ```bash 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](https://docs.derive.xyz) - [Derive Platform](https://www.derive.xyz) - [Lyra Finance](https://lyra.finance) - [MCP Protocol](https://modelcontextprotocol.io) - [CCXT Derive Integration](https://github.com/ccxt/ccxt/blob/master/python/ccxt/derive.py) ## 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.