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) orP(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:
- DERIVE_WALLET: Your Ethereum wallet address
- DERIVE_PRIVATE_KEY: Optional, used for signing transactions
Uses wallet-based authentication:
X-LyraWallet: Your wallet addressX-LyraTimestamp: Current timestampX-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=1000for efficient historical data fetches - Batch related queries together
- Avoid polling the same endpoint more than once per second
- Check
get_accountfor 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_WALLETenvironment variable is set - Check wallet address is correct
- For trading, ensure
DERIVE_PRIVATE_KEYis 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_subaccountsto 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_ENVIRONMENTsetting matches your API credentials
Additional Resources
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.