Skip to main content
Glama

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

Related MCP server: GearTrade MCP Server

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

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.

Available Tools

31 tools
cancel_all_ordersA

Cancel all open orders for a subaccount. Optionally filter by currency or instrument. Requires authentication.

Inputs: subaccount_id (required), currency, instrument_name.

cancel_orderC

Cancel an open order by order ID. Requires authentication.

Inputs: subaccount_id (required), order_id (required).

execute_quoteC

Execute a quoted trade at the quoted price. Requires authentication.

Inputs: subaccount_id (required), quote_id (required).

get_accountB

Get account details including subaccounts, rate limits, fee structure, and account status. Requires authentication.

Inputs: wallet.

get_balanceA

Get account balance across all subaccounts including collaterals and open order margins. Requires authentication.

Inputs: wallet.

get_collateralsC

Get collateral information for a subaccount including amounts, prices, and margin contributions. Requires authentication.

Inputs: subaccount_id (required).

get_currenciesB

Get all available currencies (underlying assets) on the platform.

Inputs: no named parameters.

get_deposit_historyB

Get deposit history with transaction hashes and statuses. Requires authentication.

Inputs: subaccount_id (required), from_timestamp, to_timestamp, page, +1 more.

get_funding_historyC

Get funding payments history (paid and received). Requires authentication.

Inputs: subaccount_id (required), instrument_name, currency, from_timestamp, +3 more.

get_funding_rate_historyC

Get historical funding rate data for perpetual contracts with timestamps and rates.

Inputs: instrument_name, currency, from_timestamp, to_timestamp, +2 more.

get_instrumentsB

Get all active instruments for a specified currency and type. Returns detailed information about tradeable assets including fees, constraints, and Greeks.

Inputs: currency (required), instrument_type (required), expired.

get_liquidation_historyB

Get liquidation events history across the platform.

Inputs: currency, instrument_name, from_timestamp, to_timestamp, +2 more.

get_liquidation_priceC

Get current liquidation price for an open position. Requires authentication.

Inputs: subaccount_id (required), instrument_name (required).

get_marginB

Get detailed margin information for a subaccount including maintenance margin, initial margin, and margin ratio. Requires authentication.

Inputs: subaccount_id (required).

get_my_tradesC

Get personal trade history with detailed trade information (side, price, fees, PnL). Requires authentication.

Inputs: subaccount_id (required), instrument_name, currency, from_timestamp, +3 more.

get_open_ordersA

Get all open orders for a subaccount with order status and details. Requires authentication.

Inputs: subaccount_id (required), currency, instrument_name.

get_option_settlement_historyC

Get historical option settlement data (expiry, settlement prices, PnL).

Inputs: currency, from_timestamp, to_timestamp, page, +1 more.

get_orderbookA

Get real-time orderbook data for a specific instrument with bid/ask levels, depth, and spread.

Inputs: instrument_name (required), depth.

get_orders_historyB

Get order history for a subaccount with filled, cancelled, and rejected orders. Requires authentication.

Inputs: subaccount_id (required), currency, instrument_name, page, +1 more.

get_positionsC

Get all open positions for a subaccount including unrealized PnL, mark price, leverage, and liquidation price. Requires authentication.

Inputs: subaccount_id (required), currency, instrument_type.

get_rfqsB

Get active RFQs for a subaccount with quotes received. Requires authentication.

Inputs: subaccount_id (required).

get_spot_feed_historyB

Get historical spot price feed data (index prices) with timestamps.

Inputs: currency (required), from_timestamp, to_timestamp, page, +1 more.

get_subaccountsB

Get all subaccounts for a wallet with labels and creation timestamps. Requires authentication.

Inputs: wallet.

get_tickerB

Get real-time ticker data for a single instrument (bid/ask, last price, 24h volume, Greeks for options).

Inputs: instrument_name (required).

get_tickersA

Get ticker information for multiple instruments at once. More efficient than get_ticker when querying many instruments.

Inputs: currency, instrument_type.

get_trade_historyA

Get tick-by-tick trade history with detailed trade information (price, size, buyer/seller, timestamp). Supports filtering and pagination.

Inputs: instrument_name, currency, instrument_type, from_timestamp, +6 more.

get_withdrawal_historyC

Get withdrawal history with transaction hashes and statuses. Requires authentication.

Inputs: subaccount_id (required), from_timestamp, to_timestamp, page, +1 more.

margin_watchB

Get margin watch information showing accounts approaching liquidation. Requires authentication.

Inputs: wallet.

place_orderA

Place a new order (limit or market). Requires authentication and private key for signing.

Inputs: subaccount_id (required), instrument_name (required), side (required), amount (required), +5 more.

replace_orderA

Replace an existing order (cancel old and place new) in one atomic operation. Requires authentication.

Inputs: subaccount_id (required), order_id (required), amount (required), price (required).

send_rfqC

Send a Request For Quote to get custom pricing from market makers. Requires authentication.

Inputs: subaccount_id (required), instrument_name (required), side (required), amount (required).

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.5/5.0

    Scored across 31 tools

    Disambiguation4/5

    Most tools have distinct purposes, with clear separation between account management, market data, order execution, and history queries. However, some overlap exists between get_ticker and get_tickers, and between get_my_trades and get_trade_history, which could cause minor confusion for an agent.

    Naming Consistency5/5

    Tool names follow a highly consistent verb_noun pattern throughout, such as get_account, place_order, and cancel_all_orders. This predictability makes it easy for agents to understand and navigate the toolset without ambiguity.

    Tool Count3/5

    With 31 tools, the count is borderline high for a trading platform server. While it covers many aspects comprehensively, it may feel heavy and potentially overwhelming for agents, though not extreme enough to be severely inappropriate.

    Completeness5/5

    The toolset provides complete coverage for a trading platform domain, including CRUD operations for orders, comprehensive account and market data access, historical queries, and specialized functions like RFQs and margin monitoring. No obvious gaps are present, enabling agents to handle full trading workflows.

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      Not graded
      maintenance
      Enables interaction with the Hyperliquid DEX for retrieving market data, managing positions, and executing trades. Supports both testnet and mainnet operations with comprehensive trading tools including order placement, cancellation, and portfolio management.
      11
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables AI assistants to perform cryptocurrency trading analysis and execution with 38+ tools including real-time market data, technical indicators, risk management, and support for both paper trading and live execution on Hyperliquid.
      7
      MIT
    • A
      license
      C
      quality
      D
      maintenance
      Provides access to the Unusual Whales API for real-time financial data, options flow analysis, dark pool activity, and congressional trading tracking. It enables users to perform comprehensive market intelligence and stock analysis across 33 different tools.
      33
      46 npm
      4
      MIT
    • A
      license
      A
      quality
      B
      maintenance
      Read-only Hyperliquid market data for AI agents: trades, liquidations, funding, open interest, candles, wallet analytics and SQL over every fill since May 2025. 36 tools, hosted, no install, no key needed.
      4
      54
      3,698 npm
      1
      MIT