MCP

MCP Server

Give AI agents access to Liquid Trading — market data, account management, order execution, and built-in safety guardrails.

Overview

Link

The Liquid MCP server exposes trading functionality to any MCP-compatible AI client — Claude Code, Claude Desktop, Cursor, and others. It uses the Python SDK for all API calls, so auth, signing, and error handling are centralized.

1Your AI client sends tool calls via MCP protocol
2liquidtrading-mcp validates inputs, enforces guardrails, and logs actions
3liquidtrading-python signs and sends requests to the REST API
4Results are returned as structured data with next-step suggestions

Installation

Link

pip

bash

pip install liquidtrading-mcp

global install (recommended)

bash

uv tool install liquidtrading-mcp

uv tool install makes the liquidtrading-mcp command available globally without activating a virtual environment. Requires Python 3.10+. The SDK (liquidtrading-python) is installed automatically as a dependency.

Claude Code Setup

Link

terminal

bash

claude mcp add liquid \
  -e LIQUID_API_KEY=lq_... \
  -e LIQUID_API_SECRET=sk_... \
  -- liquidtrading-mcp

Claude Desktop Setup

Link

claude_desktop_config.json

json

{
  "mcpServers": {
    "liquid": {
      "command": "liquidtrading-mcp",
      "env": {
        "LIQUID_API_KEY": "lq_...",
        "LIQUID_API_SECRET": "sk_...",
        "MAX_ORDER_USD": "1000",
        "DAILY_LOSS_LIMIT": "5000"
      }
    }
  }
}

HTTP Transport

Link

For remote or multi-client setups, run over streamable HTTP on port 4243:

terminal

bash

LIQUID_API_KEY=lq_... \
LIQUID_API_SECRET=sk_... \
liquidtrading-mcp --http

Environment Variables

Link

Variable	Default	Description
LIQUID_API_KEY	—	Your Liquid API key
LIQUID_API_SECRET	—	Your Liquid API secret
LIQUID_BASE_URL	https://api.liquid.trade	API base URL
MAX_ORDER_USD	1000	Maximum single order size in USD
DAILY_LOSS_LIMIT	5000	Daily cumulative realized loss cap in USD
LIQUID_MCP_AUDIT_PATH	~/.liquidtrading-mcp/trades.jsonl	JSONL audit log path

API key and secret must both be set. If MAX_ORDER_USD exceeds DAILY_LOSS_LIMIT, the server logs a warning at startup.

Market Data Tools

Link

Read-only tools for market discovery and analysis. These are safe to call at any time.

Tool	Parameters	Returns
get_markets	—	All tradeable symbols with max leverage and decimals
get_ticker	symbol	Mark price, 24h volume, funding rate, min order info
get_orderbook	symbol, depth	L2 snapshot with bid/ask depth
get_candles	symbol, interval, limit, start, end	OHLCV candle data

Example: ask your agent "What's the current BTC price and funding rate?" and it will call get_ticker("BTC-PERP") automatically.

Account Tools

Link

Tool	Returns
get_account	Equity, margin used, available balance, account value
get_balances	Detailed balance breakdown with cross-margin summary
get_positions	Open positions with size, leverage, PnL, liquidation price

Example: "Show me my current positions and PnL" triggers get_positions and returns a structured summary.

Order Tools

Link

Destructive tools that modify state. All support dry_run mode for previewing actions without execution.

Tool	Description
place_order	Place market or limit order (size in USD notional)
place_bracket_order	Place order with required TP and SL — safest entry tool for agents
get_open_orders	List all open orders
get_order	Fetch a specific order by ID
cancel_order	Cancel a single order
cancel_all_orders	Cancel all open orders

Example: "Buy $200 of ETH with 3x leverage, TP at 4200 and SL at 3800" triggers place_bracket_order with the appropriate parameters.

Position Tools

Link

Tool	Description
close_position	Full or partial close (partial size in coin units)
set_tp_sl	Set or update take-profit and/or stop-loss
update_leverage	Change leverage (1-200) and margin mode
update_margin	Adjust isolated margin

Example: "Close half my BTC position" triggers close_position with the appropriate coin-unit size.

Helper Tools

Link

Tool	Description
calculate_token_amount	Convert USD amount to token count at current mark price
calculate_position_size	Convert portfolio allocation % to USD and token amount
validate_trade	Pre-flight checks: size limits, daily loss, balance, symbol validity

Validate before trading

validate_trade should be called before larger orders. It checks the order against size limits, daily loss caps, available balance, and symbol validity — and returns clear pass/fail with reasons.

Resources

Link

MCP resources provide context that agents can read without calling a tool.

URI	Description
liquid://portfolio	Current account summary and open positions
liquid://risk	Guardrail state: limits, daily loss tracking, exposure

Prompt Templates

Link

Built-in prompts encode Liquid-specific trading guidance for agents — perpetual futures semantics, funding awareness, leverage caution, and TP/SL best practices.

Prompt	Use Case
scalp	Short-term momentum trades with tight stops
swing	Multi-day directional trades
funding_arb	Funding rate arbitrage strategies
momentum_scan	Market scanning for momentum setups

Safety Guardrails

Link

MAX_ORDER_USD caps every individual order (enforces $10 minimum)
Daily loss tracker records realized losses by UTC date and blocks new orders when the cap is hit
Dry run mode on all destructive tools — agents can preview actions without execution
JSONL audit trail logs every trade operation including dry runs
Structured error recovery returns next_steps guidance so agents can self-correct
High leverage warnings trigger automatically above 20x

Troubleshooting

Link

Problem	Solution
Tools don't appear in your client	Restart the MCP client after config changes. Verify liquidtrading-mcp is installed and on PATH.
Authentication errors	Check both LIQUID_API_KEY and LIQUID_API_SECRET are set and valid.
Orders fail with scope error	Your API key needs TRADE scope. Create a new key with read+trade permissions.
Unexpected position state after timeout	Call get_positions and get_open_orders to reconcile. Never retry a failed mutation blindly.