Imported from elliottech/lighter-agent-kit (SKILL.md). Install upstream with npx skills add elliottech/lighter-agent-kit. Copyright stays with the author.

Lighter Agent Kit

Trade on Lighter or its Robinhood Chain deployment using the same commands.

Scripts live in this skill's scripts/ directory. Read commands use query.py, write commands use trade.py. Every command prints structured JSON to stdout. Errors are always in JSON as {"error": "..."}.

Commands use <group> <action> syntax mirroring the Lighter UI (e.g. market stats, order limit, orders open).

For response schemas and details, see the references/ folder.

Install

Copy this folder to one of the standard Claude Code skill locations:

• Personal (all projects): ~/.claude/skills/lighter-agent-kit/
• Project-level (this repo only): .claude/skills/lighter-agent-kit/

On first call, lighter-sdk and its transitive deps will be installed into <skill>/.vendor/pyX.Y/. Every version is pinned by requirements.lock. Supported targets are Apple Silicon Macs plus Linux x86_64/arm64. Intel Macs are not supported by this kit.

Requires network egress to the selected Lighter host (mainnet.zklighter.elliot.ai, testnet.zklighter.elliot.ai, api.rh.lighter.xyz, or api.rh-testnet.lighter.xyz), pypi.org / files.pythonhosted.org, and github.com (pip clones the pinned lighter-sdk build from GitHub). On Claude.ai's sandbox the default egress allowlist doesn't include github.com — you'll need to expand it before first run.

Read commands work with no credentials. Write commands and account-private reads will first check environment variables and then your personal credentials file — see references/env-vars.md.

How to Handle User Requests

1. Symbol convention: perp-bare, spot-pair. Perp markets use bare tickers (BTC, ETH, SOL, LIT); spot markets use quote-qualified pairs (ETH/USDC on Lighter, AAPL/USDG on Robinhood Lighter). The presence of / is the single discriminator — no --market_type flag is needed on symbol-resolved commands. Numeric market_index is also accepted as an escape hatch.
2. Symbol resolution is automatic. Market symbols resolve from the live order-books API and are cached on disk for 5 minutes per host, so query.py, trade.py, and paper.py share the same market map across calls. Fund assets resolve against the selected deployment; collateral aliases its quote asset when unambiguous. Only when the user says something you can't confidently map (e.g. "brent oil", "gold", "silver"), run python3 scripts/query.py market list --search <substring> [--market_type perp|spot] first to discover it. These usually appear under ticker-style symbols like BRENTOIL, XAU, and XAG.
3. Side accepts both forms. --side buy|sell|long|short — both are accepted on perp and spot. Normalized internally to canonical (long/short for perp, buy/sell for spot).
4. Filter at the source on high-cardinality reads. market funding, market stats, and market info accept --symbol / --market_index / --exchange — always pass them when you only need one row.
5. Run the matching script: python3 scripts/query.py <group> <action> ARGS for reads, python3 scripts/trade.py <group> <action> ARGS for writes. Paths are relative to this skill's directory.
6. Parse the JSON and present it clearly.
7. Account-scoped commands and LIGHTER_ACCOUNT_INDEX. Two cases:
   • Public reads (account info, account apikeys) accept --account_index and default to LIGHTER_ACCOUNT_INDEX when omitted.
   • Authenticated reads (account limits, portfolio performance, orders open, orders history) are self-only using LIGHTER_ACCOUNT_INDEX instead of --account_index because the auth token is bound to that account.

Diagnostic (optional): if a call fails with an import lighter style error, run python3 scripts/bootstrap.py to verify the SDK vendored correctly. It should return a response with status: ok field. You should never need to run this in a healthy session.

Read Commands (query.py)

Public reads — no credentials

Account-private reads — require LIGHTER_API_PRIVATE_KEY + LIGHTER_ACCOUNT_INDEX + LIGHTER_API_KEY_INDEX

These endpoints generate a short-lived auth token from your configured credentials on every call. The auth token is bound to LIGHTER_ACCOUNT_INDEX, so all four commands below are self-only — they do not accept --account_index and there is no way to query a different account from the one whose private key signed the token.

Platform note: on claude.ai's sandboxed bash environment there is no persistent shell to export env vars into, and pasting an API private key into chat is not acceptable. Treat the four commands above as effectively Claude Code / Cursor / desktop only. On claude.ai, fall back to the public reads or direct the user to the Lighter web/mobile UI for account-private views.

Sanity check: python3 scripts/health.py returns {"status": "ok", "version": "..."} without touching the SDK — useful to confirm the skill loads at all.

See references/schemas-read.md for the full response shapes.

Write Commands (trade.py)

All write commands require credentials. Prices and amounts are in human units (e.g. --price 4050.5 --amount 0.1); the script fetches market metadata and scales them to integer ticks/lots automatically. The response echoes effective_amount / effective_price so you can see what actually landed after rounding.

Side accepts both forms: --side buy|sell|long|short. Both are accepted on perp and spot markets. Normalized internally to canonical (long/short for perp, buy/sell for spot).

Symbol convention: The positional <symbol> argument is a perp ticker (BTC, ETH), a spot pair (ETH/USDC, LIT/USDC), or a numeric market_index (1). The / in a spot symbol is the discriminator — no --market_type flag is needed.

Spot trading: every order command works transparently for spot markets — just pass a spot pair like ETH/USDC. Use query.py market list --market_type spot to discover them. On spot markets, --reduce_only and the position leverage / position margin commands are no-ops — spot has no leveraged positions.

order limit and order market return a client_order_index — save it; it is the handle for later order modify / order cancel.

Example — move deployment collateral from perp to spot to fund a spot buy:

python3 scripts/trade.py funds transfer --asset collateral --amount 250 \
    --from_route perp --to_route spot

Example — enable SPY collateral on Robinhood Lighter:

python3 scripts/query.py account info
python3 scripts/trade.py account mode --mode unified
python3 scripts/query.py account info  # wait until account_trading_mode is 1
python3 scripts/trade.py account collateral --asset SPY --mode enabled
python3 scripts/query.py account info

The two write commands above require separate, explicit user approval. account collateral --mode enabled rejects assets the selected deployment does not mark collateral-eligible and rejects Classic-mode accounts.

Every command supports --help. See references/schemas-write.md for the response envelope, precision echoback, and error-code table.

Paper Trading (paper.py)

Simulate trades against real Lighter order book snapshots without credentials, without broadcasting, and without risk. All state is local.

Shared-subset commands use <group> <action> shape identical to trade.py, so swapping the script name swaps the engine. Paper-only lifecycle commands stay flat.

Commands

Paper-only (flat):

Shared subset (mirrors trade.py shape):

Swap rule: swap trade.py ↔ paper.py to switch engines:

# live
python3 scripts/trade.py order market BTC --side long --amount 0.1

# paper — same call, same args, no live broadcast
python3 scripts/paper.py order market BTC --side long --amount 0.1

Tiers: standard (0/0 bps), premium (2.8/0.4 bps, default), premium_1 through premium_7. See references/schemas-paper.md for full tier table and response shapes.

Paper vs Live Caveats

These structural simulator limits cause paper-to-live PnL divergence, roughly ordered by how often they bite:

1. Maker fills never occur. Every paper fill is charged taker fee, even an IOC at the limit price. Live resting limits would pay maker and often get a better effective price.
2. No order-impact model. Paper orders walk the real book but don't move it. A size that clears 3 levels in paper would, live, push those levels and make the next entry worse.
3. No latency / partial-fill modeling. Paper fills instantly in full if depth exists. Live orders can miss entries or fill partially.
4. No funding accrual. For positions held across funding intervals, this is typically the dominant PnL drag/credit. Paper ignores it.
5. Cross-margin only. Strategies depending on isolated-margin blast-radius containment cannot be paper-validated.

Secondary items:

• No credentials required for paper mode
• Perp-only (market_index >= 2048 is rejected)
• Only MARKET and IOC order types (no resting limits, no stop, no TP, no post-only)
• Local-only state; rm "$LIGHTER_PAPER_STATE_PATH" (or the default path ~/.lighter/lighter-agent-kit/paper-state.json) is a valid nuclear reset

Environment Variables

See references/env-vars.md. TL;DR: public reads need nothing; for account-private reads and write commands, set LIGHTER_API_PRIVATE_KEY, LIGHTER_ACCOUNT_INDEX, and LIGHTER_API_KEY_INDEX as env vars or in your personal credentials file.

Safety Notes

• Write commands sign and broadcast immediately. Claude Code's per-tool approval prompt is the user's confirmation step — the user sees the exact command before it runs.
• funds withdraw, funds transfer, and order amounts are validated client-side (> 0, deployment-reported minimums, market/asset exists, precision fits).
• funds withdraw is not necessarily an instant wallet credit. A successful response means the withdrawal request was accepted by Lighter. The balance may leave the selected route immediately, while the actual funds move through Lighter's withdrawal / pending-balance / claim flow before showing up in the user's wallet.
• order close_all is a high-impact, account-wide write. Treat it like funds withdraw: require explicit user approval before running the non-preview form, always run --preview first and show the plan to the user, and never infer intent from vague prompts ("tidy up", "reset my account", "start fresh"). Ask the user to confirm in plain language before the real call.
• account mode and account collateral change account-wide risk configuration. Read query.py account info, explain the resulting mode/collateral change, and get explicit user approval before each write. Verify with account info afterward.
• The deployment is selected with LIGHTER_HOST. Use https://testnet.zklighter.elliot.ai or https://api.rh-testnet.lighter.xyz for testing before the corresponding mainnet.
• First call installs lighter-sdk into <skill>/.vendor/pyX.Y/. Expect ~15–40s on a cold session; subsequent calls are instant. Nothing is written outside the skill folder, so uninstalling is rm -rf <skill>/.vendor.

Credential Security — MANDATORY

Never read, cat, print, echo, or display the credentials file or any environment variable containing a private key. This includes:

• cat ~/.lighter/lighter-agent-kit/credentials
• echo $LIGHTER_API_PRIVATE_KEY
• env | grep LIGHTER
• Reading .envrc or .env files
• Any other command that would output secret values to stdout/stderr

Never write your own env-var probe (echo $..., python3 -c "print(os.environ.get(...))") — they miss the credentials file and risk leaking the secret. Secret values inside the SDK are wrapped in SecretValue objects that print [REDACTED]; do not attempt to bypass this.

What capabilities are allowed