# lighter-mcp A [Model Context Protocol](https://modelcontextprotocol.io) server for [Lighter](https://lighter.xyz) — 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](https://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):** ```bash 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:** ```bash lighter-mcp-approve --revoke ``` Sets the approval to zero fees. Or simpler — disable client-side without an on-chain change: ```bash # 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 ```bash 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": "", "LIGHTER_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 ```yaml mcp_servers: lighter: command: "python" args: ["-m", "lighter_mcp"] env: LIGHTER_URL: "https://mainnet.zklighter.elliot.ai" LIGHTER_ACCOUNT_INDEX: "<sub>" LIGHTER_PRIVATE_KEY: "" 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= LIGHTER_INTEGRATOR_MAKER_FEE= # 100 = 1 bp LIGHTER_INTEGRATOR_TAKER_FEE= # 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</sub>