Liquidity.io Docs

Agentic trading uses an AI assistant as an intermediary between you and the exchange. You describe your intent in natural language. The agent translates it into API calls, validates the results, and reports back. You stay in control -- the agent proposes, you approve.

This guide covers the end-to-end setup, common workflows, risk controls, and best practices for institutional use.

Prerequisites

Requirement	Purpose
Liquidity.io account	Exchange access, KYC complete
API key pair	Trading credentials (see Onboarding)
Claude Code	AI agent CLI
Node.js 18+	MCP server runtime

Setup

1. Install Claude Code

npm install -g @anthropic-ai/claude-code

2. Install the MCP Server

npm install -g @liquidityio/mcp @liquidityio/skills

3. Configure the MCP Server

Create .mcp.json in your working directory:

{
  "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"
      }
    }
  }
}

4. Start a Session

claude

Claude Code detects the MCP configuration and loads the Liquidity.io tools automatically. Verify with:

> What tools do you have for Liquidity.io?

I have access to the following Liquidity.io tools:
- get_quote: Real-time quotes
- get_orderbook: Order book depth
- place_order: Submit orders
- cancel_order: Cancel orders
- get_portfolio: Account balances
- get_open_orders: Open order list
- get_trades: Recent trades
- get_markets: Available instruments

Workflows

Natural Language Order Placement

> Buy 100 shares of AAPL at market

I'll place a market buy order for 100 AAPL.

[Calling place_order: symbol=AAPL, side=buy, type=market, quantity=100]

Order placed successfully:
  Order ID:  ord_9f2a3c4d
  Symbol:    AAPL
  Side:      BUY
  Type:      MARKET
  Quantity:  100
  Status:    FILLED
  Avg Price: $244.82
  Total:     $24,482.00

Conditional Orders

> If BTC-USD drops below $80,000, buy 0.5 BTC with a limit at $79,500

I'll monitor BTC-USD for you.

[Calling get_quote: symbol=BTC-USD]

Current price: $84,252. This is above your $80,000 trigger.
I'll check periodically. When BTC-USD bid drops below $80,000,
I'll place a limit buy for 0.5 BTC at $79,500.

Note: I can only monitor while this session is active.
For persistent conditional orders, use a limit order directly
or configure an alert in the dashboard.

Portfolio Analysis

> Show me my portfolio with current market values and allocation percentages

[Calling get_portfolio]
[Calling get_quote for each held asset]

Portfolio Summary
━━━━━━━━━━━━━━━━
Total Value: $502,340.00

Asset    Quantity    Price        Value         Allocation
USD      125,430     --           $125,430.00   24.97%
BTC      2.50        $84,252.00   $210,630.00   41.93%
ETH      45.00       $3,180.00    $143,100.00   28.49%
AAPL     95          $244.00      $23,180.00     4.61%

Top concentration: BTC at 41.93%
Cash position: 24.97%

Multi-Step Research and Trade

> I want to add ETH exposure. Show me the orderbook,
> then buy $10,000 worth at the best available price.

Step 1: Checking the ETH-USD orderbook.

[Calling get_orderbook: symbol=ETH-USD, depth=10]

ETH-USD Orderbook (top 5):
  Bids                    Asks
  $3,178 x 12.5           $3,180 x 8.2
  $3,176 x 20.1           $3,182 x 15.4
  $3,174 x 8.7            $3,184 x 22.0
  $3,172 x 31.2           $3,186 x 5.6
  $3,170 x 14.8           $3,188 x 18.9

Best ask: $3,180. For $10,000, that's approximately 3.14 ETH.
The top ask level has 8.2 ETH available, so your order fills
entirely at the first level with no slippage.

Shall I proceed with a market buy of 3.14 ETH-USD?

> Yes

[Calling place_order: symbol=ETH-USD, side=buy, type=market, quantity=3.14]

Done:
  Order ID:  ord_a1b2c3d4
  Filled:    3.14 ETH at $3,180.00
  Total:     $9,985.20

Risk Controls and Guardrails

Server-Side Limits

The MCP server enforces configurable risk limits before any order reaches the exchange:

{
  "risk": {
    "maxOrderSizeUSD": 50000,
    "maxPositionSizeUSD": 500000,
    "maxDailyLossUSD": 10000,
    "maxOrdersPerMinute": 10,
    "allowedSymbols": ["AAPL", "BTC-USD", "ETH-USD"],
    "allowedOrderTypes": ["market", "limit"],
    "requireConfirmation": true
  }
}

When requireConfirmation is true, the agent must present the order details and receive explicit user approval before calling place_order. This is the recommended setting for all non-automated workflows.

What the Agent Cannot Do

Regardless of configuration:

No withdrawals or fund transfers
No account modification (KYC, settings, API keys)
No access to other accounts or tenants
No bypassing of accreditation requirements
No disabling of risk checks

Kill Switch

If the agent behaves unexpectedly:

Close the Claude Code session (Ctrl+C terminates all pending tool calls)
Revoke the API key in the Liquidity.io dashboard
All open orders placed by that key are automatically cancelled on key revocation

Audit Log

Every tool call made through the MCP server is logged:

2026-03-19T10:15:32Z  get_quote         symbol=BTC-USD                   200  12ms
2026-03-19T10:15:33Z  get_orderbook     symbol=BTC-USD depth=10          200  18ms
2026-03-19T10:15:45Z  place_order       symbol=BTC-USD side=buy qty=0.5  200  45ms

Logs are written to stderr by default. Configure LIQUIDITYIO_LOG_FILE to write to a file.

Backtesting with AI Agents

The MCP server supports a replay mode that feeds historical data instead of live market data. This lets you test agent strategies against past price action.

Configuration

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

Backtest Session

> Backtest: Buy 0.1 BTC every Monday at market open for the last 3 months.
> Report total cost basis and current value.

Running DCA simulation from 2026-01-01 to 2026-03-01...

Week   Date         Price       Quantity   Cost
1      2026-01-06   $78,200     0.1        $7,820
2      2026-01-13   $79,450     0.1        $7,945
3      2026-01-20   $77,100     0.1        $7,710
...
12     2026-03-17   $84,252     0.1        $8,425

Total BTC acquired: 1.2
Total cost basis:   $96,340
Current value:      $101,102 (at $84,252)
Return:             +4.94%

Example Session: Institutional Workflow

The following transcript shows a complete workflow for a portfolio manager:

> Good morning. Show me overnight changes across my portfolio.

[Calling get_portfolio]
[Calling get_quote for BTC-USD, ETH-USD, AAPL, MSFT, GOOGL]

Overnight Summary (since market close):
  BTC-USD:  $84,252 (+1.2%)  -- your position: 2.5 BTC, +$2,520
  ETH-USD:  $3,180  (+0.8%)  -- your position: 45 ETH, +$1,140
  AAPL:     $244.82 (market closed, last change +0.5%)
  Portfolio unrealized: +$3,660

> I want to take some BTC profit. Sell 0.5 BTC but only if I can
> get $84,200 or better.

[Calling get_orderbook: symbol=BTC-USD]

Current best bid: $84,248. Placing limit sell at $84,200.

[Calling place_order: symbol=BTC-USD, side=sell, type=limit,
 quantity=0.5, price=84200]

Limit sell placed:
  Order ID:  ord_e5f6g7h8
  Symbol:    BTC-USD
  Side:      SELL
  Quantity:  0.5
  Price:     $84,200.00
  Status:    OPEN

I'll check back on this. Would you like me to monitor the fill?

> Yes, and if it fills, move the proceeds to ETH.

Understood. I'll monitor ord_e5f6g7h8. When filled, I'll use
the proceeds (~$42,100) to buy ETH-USD at market.

[Polling get_open_orders...]

Update: Order filled at $84,250 (price improvement of $50).
Proceeds: $42,125.00

[Calling place_order: symbol=ETH-USD, side=buy, type=market,
 quantity=13.24]

ETH purchased:
  13.24 ETH at $3,181.20
  Total: $42,119.49
  Remaining USD: $5.51

Rotation complete. Your ETH position is now 58.24 ETH.

Best Practices for Institutional Use

API Key Management

Create separate API keys for each agent instance or strategy
Set per-key position limits and daily loss limits
Use IP allowlisting to restrict key usage to known infrastructure
Rotate keys on a regular schedule (quarterly minimum)
Store keys in a secrets manager (AWS Secrets Manager, HashiCorp Vault, or Liquid KMS)

Compliance

The MCP server logs every tool call with full parameters. Export logs to your compliance system.
All trades go through the same accreditation and RegCF checks as manual trades.
For regulated entities: designate the AI agent as a tool, not a decision-maker. A human must approve each order (use requireConfirmation: true).
Pre-trade compliance checks (restricted lists, position limits, cross-trading rules) are enforced at the exchange level regardless of order source.

Deployment Patterns

Single-user local: Run the MCP server on your workstation. Simplest setup. API keys in environment variables.

Team shared server: Run the MCP server on an internal host. Each team member connects via Claude Code with their own API key. The server runs as an HTTP SSE transport.

Automated strategy: Run Claude Code in a headless loop with a fixed prompt. The agent executes a defined strategy (e.g., rebalance daily at 9:00 AM ET). Use requireConfirmation: false with tight risk limits.

# Headless rebalance
echo '/rebalance --target {"BTC":0.4,"ETH":0.3,"USD":0.3}' | claude --no-interactive

Latency Considerations

The MCP server adds approximately 5-15ms of overhead per tool call (parameter validation, auth header injection, response normalization). For latency-sensitive strategies, use the SDK directly. The MCP layer is designed for human-in-the-loop workflows where milliseconds are not critical.

Method	Typical Latency	Use Case
MCP via Claude Code	50-200ms per action	Portfolio management, research, manual trading
TypeScript SDK	5-20ms per call	Automated strategies, market making
REST API direct	5-15ms per call	Custom integrations, high-frequency
WebSocket	Sub-ms updates	Real-time data, order status streaming

Agentic Trading