Liquidity.io Docs

The Model Context Protocol (MCP) is a standard interface that lets AI agents call structured tools. The @liquidityio/mcp server exposes the Liquidity.io exchange as a set of tools that any MCP-compatible client (Claude Code, Claude Desktop, Cursor, or custom agents) can invoke directly.

Instead of writing code, you describe what you want in natural language. The AI agent translates your intent into tool calls, executes them against the exchange, and returns structured results.

How It Works

You (natural language) -> AI Agent (Claude) -> MCP Server -> Liquidity.io API
                                                                    |
You (formatted results) <- AI Agent (interpretation) <- JSON response

The MCP server runs locally or in your infrastructure. It authenticates to Liquidity.io on your behalf and exposes a fixed set of tools with validated parameters. The AI agent never sees your API keys directly -- they are configured in the server environment.

Available Tools

Tool	Description	Parameters
`get_quote`	Real-time bid/ask/last for any asset	`symbol`
`get_orderbook`	Full depth-of-book with aggregated levels	`symbol`, `depth?`
`place_order`	Submit market or limit orders	`symbol`, `side`, `type`, `quantity`, `price?`
`cancel_order`	Cancel an open order by ID	`order_id`, `symbol`
`get_portfolio`	Current balances across all assets	--
`get_open_orders`	List all open orders, optionally filtered	`symbol?`
`get_trades`	Recent trade history for a symbol	`symbol`, `limit?`
`get_markets`	List all tradeable instruments	--

Each tool validates its inputs via JSON Schema before calling the exchange API. Invalid parameters return a typed error, not a silent failure.

Installation

npm install -g @liquidityio/mcp

The package provides a CLI binary (liquidityio-mcp) and a programmatic API.

Configuration

Environment Variables

export LIQUIDITYIO_API_URL="https://api.liquidity.io/v1"
export LIQUIDITYIO_API_KEY="your-api-key"
export LIQUIDITYIO_API_SECRET="your-api-secret"

For the sandbox environment:

export LIQUIDITYIO_API_URL="https://api.next.liquidity.io/v1"

Claude Code

Create .mcp.json in your project root:

{
  "mcpServers": {
    "liquidityio": {
      "command": "npx",
      "args": ["@liquidityio/mcp", "serve"],
      "env": {
        "LIQUIDITYIO_API_URL": "https://api.liquidity.io/v1",
        "LIQUIDITYIO_API_KEY": "your-api-key",
        "LIQUIDITYIO_API_SECRET": "your-api-secret"
      }
    }
  }
}

Claude Desktop

liquidityio-mcp install-desktop

Or manually add to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "liquidityio": {
      "command": "npx",
      "args": ["@liquidityio/mcp", "serve"],
      "env": {
        "LIQUIDITYIO_API_URL": "https://api.liquidity.io/v1",
        "LIQUIDITYIO_API_KEY": "your-api-key",
        "LIQUIDITYIO_API_SECRET": "your-api-secret"
      }
    }
  }
}

Restart Claude Desktop after editing the config.

Programmatic Usage

import { createMcpServer } from '@liquidityio/mcp';

const server = createMcpServer({
  apiUrl: process.env.LIQUIDITYIO_API_URL,
  apiKey: process.env.LIQUIDITYIO_API_KEY,
  apiSecret: process.env.LIQUIDITYIO_API_SECRET,
});

server.listen();

Tool Call Examples

Get a Quote

Prompt: "What's the current price of AAPL?"

The agent calls:

{
  "tool": "get_quote",
  "parameters": {
    "symbol": "AAPL"
  }
}

Response:

{
  "symbol": "AAPL",
  "bid": "244.80",
  "ask": "244.85",
  "last": "244.82",
  "volume24h": "52341200",
  "change24h": "1.23",
  "timestamp": 1742400000000
}

Place a Limit Order

Prompt: "Buy 10 shares of AAPL at $240 limit."

The agent calls:

{
  "tool": "place_order",
  "parameters": {
    "symbol": "AAPL",
    "side": "buy",
    "type": "limit",
    "quantity": "10",
    "price": "240.00"
  }
}

Response:

{
  "orderId": "ord_8f3a2b1c",
  "symbol": "AAPL",
  "side": "buy",
  "orderType": "limit",
  "status": "open",
  "quantity": "10",
  "price": "240.00",
  "filledQuantity": "0",
  "createdAt": 1742400000000
}

Get Portfolio

Prompt: "Show me my current portfolio."

The agent calls:

{
  "tool": "get_portfolio",
  "parameters": {}
}

Response:

{
  "balances": [
    { "asset": "USD", "free": "125430.00", "locked": "2400.00" },
    { "asset": "AAPL", "free": "150", "locked": "0" },
    { "asset": "BTC", "free": "2.5", "locked": "0.1" },
    { "asset": "ETH", "free": "45.0", "locked": "0" }
  ]
}

Get Orderbook

Prompt: "Show me the BTC-USD orderbook, top 5 levels."

{
  "tool": "get_orderbook",
  "parameters": {
    "symbol": "BTC-USD",
    "depth": 5
  }
}

Response:

{
  "symbol": "BTC-USD",
  "bids": [
    ["84250.00", "0.523"],
    ["84245.00", "1.100"],
    ["84240.00", "0.750"],
    ["84235.00", "2.300"],
    ["84230.00", "0.412"]
  ],
  "asks": [
    ["84255.00", "0.480"],
    ["84260.00", "0.920"],
    ["84265.00", "1.350"],
    ["84270.00", "0.610"],
    ["84275.00", "1.800"]
  ]
}

curl Equivalents

Every MCP tool call maps to a REST endpoint. For automation outside of AI agents:

# Get quote
curl -H "Authorization: Bearer $TOKEN" \
  "https://api.liquidity.io/v1/ticker/AAPL"

# Place order
curl -X POST -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"symbol":"AAPL","side":"buy","type":"limit","quantity":"10","price":"240.00"}' \
  "https://api.liquidity.io/v1/orders"

# Get balances
curl -H "Authorization: Bearer $TOKEN" \
  "https://api.liquidity.io/v1/account/balances"

# Get orderbook
curl -H "Authorization: Bearer $TOKEN" \
  "https://api.liquidity.io/v1/orderbook/BTC-USD?depth=5"

Security Model

What AI Agents Can Do

Read market data (quotes, orderbooks, trades)
Read account state (balances, open orders)
Place orders within configured risk limits
Cancel their own orders

What AI Agents Cannot Do

Withdraw funds or transfer assets off-platform
Modify account settings, KYC, or API keys
Access other users' data or cross-tenant information
Bypass accreditation requirements
Exceed risk manager limits (position size, daily loss)

Key Isolation

API keys used by the MCP server should be scoped to trading permissions only. Never use admin-level keys. The recommended setup:

Create a dedicated API key pair in the Liquidity.io dashboard
Assign only trade and read permissions
Set IP allowlisting to the machine running the MCP server
Configure position size and daily loss limits at the API key level
Store keys in environment variables or a secrets manager -- never in source code

Audit Trail

Every tool call is logged with the originating API key, timestamp, and parameters. The audit log is available in the Liquidity.io dashboard under Account > API Activity.

Architecture

The MCP server is built on @modelcontextprotocol/sdk and uses the HIP-0300 action-routed dispatch pattern from @liquidityio/mcp. Each tool is a thin wrapper around the Liquidity.io REST API that handles parameter validation, authentication header injection, and response normalization.

@liquidityio/mcp
├── tools/
│   ├── get-quote.ts       # GET /v1/ticker/:symbol
│   ├── get-orderbook.ts   # GET /v1/orderbook/:symbol
│   ├── place-order.ts     # POST /v1/orders
│   ├── cancel-order.ts    # DELETE /v1/orders/:id
│   ├── get-portfolio.ts   # GET /v1/account/balances
│   ├── get-open-orders.ts # GET /v1/orders?status=open
│   ├── get-trades.ts      # GET /v1/trades/:symbol
│   └── get-markets.ts     # GET /v1/markets
├── auth.ts                # HMAC signature + timestamp
├── server.ts              # MCP server lifecycle
└── cli.ts                 # CLI entry point

The server runs as a stdio transport by default (for Claude Desktop / Claude Code) or as an HTTP SSE transport for remote deployments.

Model Context Protocol

On this page