lighter-mcp

<!-- mcp-name: io.github.0xDegenMo/lighter-mcp -->

lighter-mcp

A Model Context Protocol server for Lighter — a zero-fee zk-rollup perpetual DEX on Ethereum.

Connect any MCP-aware client (Claude Desktop, Cursor, Hermes, custom Anthropic SDK apps) and trade Lighter perpetuals natively: place orders, manage positions, set on-chain stop-loss / take-profit, query markets and account state.

New to Lighter?

Sign up here for a 5% bonus on your first trades:

app.lighter.xyz/?referral=0XDEGENMO

The bonus is applied automatically at account creation — the referral code only works during signup, not after. If you already have a Lighter account, skip this section.

Free + sustained by a small optional fee

This MCP is free and open-source. You can install it, run it, and trade through it without paying anyone.

If you find it useful, you can opt-in to a small fee that helps keep the project sustained — one on-chain transaction, no recurring action. The fee is 1 bp maker (0.01%) / 2 bps taker (0.02%) on your own trades:

| Your trade volume | Per-trade cost (taker) | Yearly cost (50 trades/month) | |---|---|---| | $1,000 | $0.20 | ~$120 | | $100 | $0.02 | ~$12 | | $50 (lighter sub-account default) | $0.01 | ~$6 |

The fee routes via Lighter's permissionless partner-integrator program to the maintainer's account 725426. No fees flow until you sign an on-chain ApproveIntegrator once. It's strictly opt-in: you can install + trade without ever approving.

Honest disclosure about Lighter's standard fees:

• Lighter Standard Accounts (retail default) currently trade with 0 maker / 0 taker fees. Approving the integrator means you pay 1-2 bps that wouldn't otherwise apply.
• Lighter Premium Accounts trade with 2/20 bps. Approving the integrator gives you 1/2 bps instead — you save money.

For Standard Accounts the approve is a small "thanks" contribution. For Premium Accounts it's a clear win-win.

How to opt in (or out)

Opt in (one-time, ~60 seconds, recommended browser flow):

lighter-mcp-approve

A localhost web page opens; connect Metamask/Rabby; click Approve; sign the EIP-191 message in your wallet. Your L1 wallet key never leaves the wallet UI — only an EIP-191 personal signature passes back to the local script.

Revoke at any time:

lighter-mcp-approve --revoke

Sets the approval to zero fees. Or simpler — disable client-side without an on-chain change:

# In your MCP server env:
LIGHTER_NO_INTEGRATOR=true

When set, integrator params aren't even attached to your orders. Zero attribution, zero potential fee flow.

Approve expires after 90 days by default — you re-approve only if you want to keep contributing. No silent lock-in.

Features

• 17 trading tools + get_status, get_signup_info, and how_to_approve_integrator diagnostics
• Three credential tiers — install + try with no credentials, opt in to more as you go
• Native on-chain SL/TP — survives client restarts
• USDC-notional market orders for simple sizing; base-amount limit orders for precision
• Multi-market — symbols auto-discovered from the order-book API
• Sub-account-first design — API key signs for a sub-account; your main wallet stays cold
• Server-side safety caps — max trade size, slippage limit, symbol allowlist
• Per-market price/size encoding — handles all listed perpetuals correctly (BTC 1-decimal, NEAR 5-decimal, etc.)

Modes

The server picks one of three modes at startup based on which env vars are set. Higher modes are strictly opt-in.

| Mode | Required env | Tools available | Use for | |---|---|---|---| | PUBLIC | _(none)_ | 7 public market-data tools (markets, candles, orderbook, funding...) | Trying it out, exploring Lighter data, building analytics | | READ | LIGHTER_ACCOUNT_INDEX | + 3 account-state tools (balance, positions) | Monitoring your account from Claude/Cursor | | TRADE | + LIGHTER_PRIVATE_KEY _(and not_ LIGHTER_READ_ONLY=true_)_ | + 8 trading tools | Autonomous / assisted trading |

In TRADE mode you can demote to read-only at any time with LIGHTER_READ_ONLY=true — order-placement tools are then not even registered.

Install

pip install 0xdegenmo-lighter-mcp
# For live trading you also need the git version of the Lighter SDK:
pip install --upgrade git+https://github.com/elliottech/lighter-python.git@main

Configure

Claude Desktop

~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

Minimal — PUBLIC mode (no Lighter account needed): ``json { "mcpServers": { "lighter": { "command": "python", "args": ["-m", "lighter_mcp"] } } } ``

Full — TRADE mode (sub-account API key required): ``json { "mcpServers": { "lighter": { "command": "python", "args": ["-m", "lighter_mcp"], "env": { "LIGHTER_URL": "https://mainnet.zklighter.elliot.ai", "LIGHTER_ACCOUNT_INDEX": "<your-sub-account-index>", "LIGHTER_PRIVATE_KEY": "<api-key-private-key>", "LIGHTER_API_KEY_INDEX": "2", "LIGHTER_MAX_QUOTE_USD": "100" } } } } ``

Restart Claude Desktop. Try: "List my Lighter markets" (PUBLIC works) or "What's my balance?" (needs READ+).

Cursor / other MCP clients

Same command and args. Check your client's MCP server config for the exact format.

Hermes Agent

mcp_servers:
  lighter:
    command: "python"
    args: ["-m", "lighter_mcp"]
    env:
      LIGHTER_URL: "https://mainnet.zklighter.elliot.ai"
      LIGHTER_ACCOUNT_INDEX: "<sub>"
      LIGHTER_PRIVATE_KEY: "<api-key-priv>"
      LIGHTER_API_KEY_INDEX: "2"

Tools

Always available (Tier 1 — PUBLIC)

• get_status — current mode, safety policy, integrator config (no secrets)
• get_signup_info — Lighter signup URL + referral code (5% bonus for new users)
• how_to_approve_integrator — instructions for opt-in / opt-out
• list_markets, get_market(symbol) — market discovery
• get_candles, get_ticker, get_orderbook, get_funding_rate — market data

With LIGHTER_ACCOUNT_INDEX (Tier 2 — READ)

• get_balance — collateral / margin-in-use / available / asset_value
• get_positions, get_position(symbol) — open positions

With LIGHTER_PRIVATE_KEY (Tier 3 — TRADE)

• set_leverage(symbol, leverage, cross)
• place_market_order(symbol, side, quote_amount_usd, reduce_only)
• place_limit_order(symbol, side, base_amount, price)
• place_stop_loss(symbol, side, base_amount, trigger_price) — on-chain, reduce-only
• place_take_profit(symbol, side, base_amount, trigger_price) — on-chain, reduce-only
• close_position(symbol)
• cancel_order(order_id, symbol)
• cancel_all_orders

Trust & Security

This server signs transactions with whatever key you put in LIGHTER_PRIVATE_KEY. Treat that as the most sensitive value in the whole config.

Why you can trust this MCP (or audit it):

• Fully open-source — every line of code lives at github.com/0xDegenMo/lighter-mcp. ~800 lines of Python total, readable in under 30 minutes.
• Sub-account isolation — the API key signs only for one Lighter sub-account; cannot withdraw funds, cannot touch your main wallet.
• Three-tier separation — tools that need credentials are only registered when those credentials are present. A PUBLIC-mode server cannot place trades even if asked.
• Integrator fees are Lighter-enforced — even if the maintainer ships malicious code that tries to skim, Lighter's protocol requires your on-chain ApproveIntegrator for fees to flow at all. Without your signature, integrator params are inert.
• Easy revoke — lighter-mcp-approve --revoke or LIGHTER_NO_INTEGRATOR=true env, takes seconds.
• Approve expires — default 90-day expiry means you re-confirm intent, never silently locked in.

Wallet hygiene

• Use a Lighter sub-account, not your main wallet. Create the sub-account in the Lighter UI, fund only what you're willing to risk, generate an API key with apiKeyIndex >= 2 for that sub-account. That key cannot withdraw — it can only sign trading transactions for that sub-account.
• Never put your main wallet seed or main signing key in env vars. This MCP doesn't need it.
• Treat LIGHTER_PRIVATE_KEY as a secret. Don't commit .env; don't paste into shared chats.

Server-side caps (enforced before the order leaves the process)

• LIGHTER_MAX_QUOTE_USD (default 100) — opening trade size cap in USDC. reduce_only=True orders bypass the cap, so closing/trimming always works.
• LIGHTER_MAX_SLIPPAGE (default 0.005 = 0.5%) — applied to market orders.
• LIGHTER_ALLOWED_SYMBOLS (default: all markets) — comma-separated allowlist. If set, trades on any other symbol are refused server-side.
• LIGHTER_API_KEY_INDEX < 2 — logged as a warning at startup. Indices 0/1 are typically reserved for the main account.

Operational notes

• Logs (stderr) include the active mode and integrator config but never the private key (only first/last few chars in the rare case keys appear in error paths).
• cancel_all_orders cancels across all markets in the sub-account. Use intentionally.
• Cross-margin: all positions in the sub-account share collateral; a bad trade can drain the whole sub-account but nothing else.

Forking for your own integrator

If you fork this project, you can route fees to your own account: ``bash LIGHTER_INTEGRATOR_ACCOUNT_INDEX=<your-account-index> LIGHTER_INTEGRATOR_MAKER_FEE=<raw> # 100 = 1 bp LIGHTER_INTEGRATOR_TAKER_FEE=<raw> # 200 = 2 bps ``

Then each install needs its own ApproveIntegrator for your account before fees flow.

Environment

| Var | Tier | Default | Description | |---|---|---|---| | LIGHTER_URL | all | mainnet | API base URL | | LIGHTER_ACCOUNT_INDEX | READ+ | _(unset)_ | Sub-account index | | LIGHTER_PRIVATE_KEY | TRADE | _(unset)_ | API-key private key (sub-account, not main wallet) | | LIGHTER_API_KEY_INDEX | TRADE | 2 | Index of the API key | | LIGHTER_READ_ONLY | any | _(unset)_ | If true, disables order-placement tools | | LIGHTER_MAX_QUOTE_USD | TRADE | 100 | Cap on opening trade size in USDC | | LIGHTER_MAX_SLIPPAGE | TRADE | 0.005 | Max slippage fraction on market orders | | LIGHTER_ALLOWED_SYMBOLS | TRADE | _(unset)_ | Comma-separated symbol allowlist | | LIGHTER_NO_INTEGRATOR | any | _(unset)_ | If true, strips integrator params entirely | | LIGHTER_INTEGRATOR_ACCOUNT_INDEX | any | 725426 | Override integrator account (forks) | | LIGHTER_INTEGRATOR_MAKER_FEE | any | 100 | Override maker fee (raw int) | | LIGHTER_INTEGRATOR_TAKER_FEE | any | 200 | Override taker fee (raw int) | | LIGHTER_MCP_LOG_LEVEL | any | INFO | Log level on stderr |

License

MIT