> For the complete documentation index, see [llms.txt](https://docs.lighter.xyz/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.lighter.xyz/developers/ai-and-agents/agent-instructions.md). # Agent instructions (AGENTS.md) A ready-to-paste AGENTS.md / CLAUDE.md / Cursor rule that teaches coding agents how to integrate Lighter correctly. Copy the block below into your repository. It gives your coding agent the rules that matter most when integrating Lighter. | Agent | Save it as | | ----------- | ------------------------------------------------------------------------------------------------------------------------------------ | | Claude Code | `CLAUDE.md` (or `AGENTS.md`) | | Cursor | `.cursor/rules/lighter.mdc` | | Devin | `AGENTS.md` in the repo root. Devin loads it automatically before it starts coding (the first 16 KiB; this file is well under that). | | Others | `AGENTS.md` | {% code title="AGENTS.md" %} ```markdown # Lighter integration rules ## Sources of truth - Docs and API reference: https://docs.lighter.xyz (index: https://docs.lighter.xyz/llms.txt; append .md to any page) - Signer: https://github.com/elliottech/lighter-go (WASM: wasm/main.go) - Look things up before writing code. Do not guess endpoint names, parameters or enum values. ## Environments - Mainnet: https://mainnet.zklighter.elliot.ai, wss://mainnet.zklighter.elliot.ai/stream, chainId 304 - Testnet: https://testnet.zklighter.elliot.ai, wss://testnet.zklighter.elliot.ai/stream, chainId 300 - Default to testnet in examples and tests. ## Accounts and keys - An L1 (Ethereum) address owns one or more integer account indexes (master + sub-accounts). - API keys are separate from the Ethereum key. Use API key indexes 4–254 (0–3 are reserved). - Registering an API key (ChangePubKey) requires the L1 wallet signature over `messageToSign`, set as `L1Sig` in tx_info. - Never hard-code, log or commit private keys. Load them from env/secret storage. - Never put a shared/server API key in frontend code. - For read-only use cases, use read-only tokens (`ro:...`), not API keys. ## Numbers - Prices and sizes are integers: value × 10^decimals, using `price_decimals` / `size_decimals` from GET /api/v1/orderBookDetails for that market. - Never hard-code market IDs or decimals outside tests. - Enforce `min_base_amount` and `min_quote_amount`. - For taker/market orders, `price` is the worst acceptable price (slippage limit). ## Transactions - Flow: sign locally with the signer → POST /api/v1/sendTx (form-urlencoded: tx_type, tx_info) → confirm via WebSocket or GET /api/v1/tx. - `code: 200` means accepted, not executed. Always confirm. - Nonces are per API key and must increase by 1 unless skipNonce=1. Get with GET /api/v1/nextNonce. Serialize sends per key. - Before re-signing after an unknown outcome, check the tx status and nextNonce; re-signing with a new nonce can place an order twice. - orderExpiry is unix milliseconds, 5 minutes–30 days ahead; use 0 for IOC orders. - clientOrderIndex must be unique across all markets and ≤ 2^48−1. - Batches: max 50 txs (same account + API key), consecutive nonces, tx_types and tx_infos as JSON-encoded strings. Prefer WebSocket jsonapi/sendtxbatch for more than ~15 txs; large REST bodies can be rejected at the CDN edge. ## WASM signer - All Sign* functions take positional args; the last two are always apiKeyIndex, accountIndex. Pass 0 for unused args, never undefined. - Check `result.error` on every call. - Do all HTTP from JavaScript: pass "" as the CreateClient URL and an explicit nonce; never use CheckClient or nonce=-1 from WASM. - wasm_exec.js must match the Go version that built the .wasm. ## WebSocket - Send a frame at least every 2 minutes ({"type":"ping"}); reconnect and resubscribe automatically. - Order book: snapshot then deltas; verify begin_nonce == previous nonce, else resubscribe. - Private channels need "auth": (token from CreateAuthToken, max 8h). ## Safety - Ask a human before: mainnet orders, withdrawals, transfers, changing account tier, registering keys. - Respect rate limits; back off on HTTP 429/405. ``` {% endcode %} ## Why these rules Each rule prevents a mistake we see often in integrations: decimals errors, nonce collisions, keys leaking into frontends, and treating `200` as "filled". See [Troubleshooting](/developers/going-to-production/troubleshooting.md). --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` GET https://docs.lighter.xyz/developers/ai-and-agents/agent-instructions.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.