Lighter Agent Kit
Handeln Sie auf Lighter oder seiner Robinhood-Chain-Bereitstellung mit denselben Befehlen.
Skripte befinden sich im scripts/-Verzeichnis dieses Skills. Lesebefehle verwenden query.py, Schreibbefehle verwenden trade.py. Jeder Befehl gibt strukturiertes JSON nach stdout aus. Fehler werden immer als JSON im Format {"error": "..."} gemeldet.
Befehle verwenden die <Gruppe> <Aktion>-Syntax, die der Lighter-UI entspricht (z. B. market stats, order limit, orders open).
Antwortschemata und Details finden Sie im Ordner references/.
Installation
Kopieren Sie diesen Ordner an einen der standardmäßigen Claude-Code-Skill-Speicherorte:
- Persönlich (alle Projekte):
~/.claude/skills/lighter-agent-kit/ - Projektebene (nur dieses Repository):
.claude/skills/lighter-agent-kit/
Beim ersten Aufruf werden lighter-sdk und seine transitiven Abhängigkeiten in <skill>/.vendor/pyX.Y/ installiert. Jede Version wird durch requirements.lock fixiert. Unterstützte Ziele sind Apple-Silicon-Macs sowie Linux x86_64/arm64. Intel-Macs werden von diesem Kit nicht unterstützt.
Erfordert Netzwerkzugriff auf den ausgewählten Lighter-Host (mainnet.zklighter.elliot.ai, testnet.zklighter.elliot.ai, api.rh.lighter.xyz, oder api.rh-testnet.lighter.xyz), pypi.org / files.pythonhosted.org und github.com (pip klont den fixierten lighter-sdk-Build von GitHub). In der Sandbox von Claude.ai enthält die standardmäßige Egress-Whitelist github.com nicht – Sie müssen sie vor dem ersten Start erweitern.
Lesebefehle funktionieren ohne Anmeldeinformationen. Schreibbefehle und kontospezifische Lesezugriffe prüfen zuerst Umgebungsvariablen und dann Ihre persönliche Credentials-Datei – siehe references/env-vars.md.
Umgang mit Benutzeranfragen
- Symbolkonvention: Perp-roh, Spot-Paar. Perp-Märkte verwenden bloße Ticker (
BTC,ETH,SOL,LIT); Spot-Märkte verwenden kursqualifizierte Paare (ETH/USDCauf Lighter,AAPL/USDGauf Robinhood Lighter). Das Vorhandensein von/ist der alleinige Unterscheider – bei symbolaufgelösten Befehlen ist kein--market_type-Flag erforderlich. Der numerischemarket_indexwird ebenfalls als Ausweichmöglichkeit akzeptiert. - Symbolauflösung erfolgt automatisch. Marktsymbole werden aus der Live-Orderbuch-API aufgelöst und 5 Minuten pro Host auf der Festplatte zwischengespeichert, sodass
query.py,trade.pyundpaper.pydie gleiche Marktzuordnung über Aufrufe hinweg verwenden. Fonds-Assets werden gegen die ausgewählte Bereitstellung aufgelöst;collateralaliasiert sein Quote-Asset, wenn dies eindeutig ist. Nur wenn der Benutzer etwas sagt, das Sie nicht sicher zuordnen können (z. B. „Brent-Öl“, „Gold“, „Silber“), führen Sie zuerstpython3 scripts/query.py market list --search <Teilstring> [--market_type perp|spot]aus, um es zu entdecken. Diese erscheinen normalerweise unter Ticker-ähnlichen Symbolen wieBRENTOIL,XAUundXAG. - Seite akzeptiert beide Formen.
--side buy|sell|long|short– beide werden für Perp und Spot akzeptiert. Intern auf die kanonische Form normalisiert (long/short für Perp, buy/sell für Spot). - Filtern Sie an der Quelle bei Lesezugriffen mit hoher Kardinalität.
market funding,market statsundmarket infoakzeptieren--symbol/--market_index/--exchange– übergeben Sie diese immer, wenn Sie nur eine Zeile benötigen. - Führen Sie das passende Skript aus:
python3 scripts/query.py <Gruppe> <Aktion> ARGUMENTEfür Lesezugriffe,python3 scripts/trade.py <Gruppe> <Aktion> ARGUMENTEfür Schreibzugriffe. Pfade sind relativ zum Verzeichnis dieses Skills. - Parsen Sie das JSON und präsentieren Sie es klar.
- Kontobezogene Befehle und
LIGHTER_ACCOUNT_INDEX. Zwei Fälle:- Öffentliche Lesezugriffe (
account info,account apikeys) akzeptieren--account_indexund verwenden standardmäßigLIGHTER_ACCOUNT_INDEX, wenn dieser weggelassen wird. - Authentifizierte Lesezugriffe (
account limits,portfolio performance,orders open,orders history) sind nur für das eigene Konto und verwendenLIGHTER_ACCOUNT_INDEXanstelle von--account_index, da das Authentifizierungstoken an dieses Konto gebunden ist.
- Öffentliche Lesezugriffe (
Diagnose (optional): Wenn ein Aufruf mit einem import lighter-Fehler fehlschlägt, führen Sie python3 scripts/bootstrap.py aus, um zu überprüfen, ob das SDK korrekt eingebunden wurde. Es sollte eine Antwort mit dem Feld status: ok zurückgeben. Sie sollten dies in einer fehlerfreien Sitzung nie ausführen müssen.
Lesebefehle (query.py)
Öffentliche Lesezugriffe – keine Anmeldeinformationen
| Befehl | Zweck |
|---|---|
system status | zkLighter-Systemstatus (Netzwerk-ID, Zeitstempel). |
market list [--market_type perp|spot] [--search X] | Kompakter Katalog {symbol, market_index, market_type}. Für Symbol-zu-Index-Nachschlagen. |
market stats [--symbol X] | Marktübersicht: Preise, 24h-Volumen, tägliche Trades. Übergeben Sie --symbol, um eine Zeile zu erhalten. |
market info [--market_type perp|spot] [--symbol X] | Vollständige Marktmetadaten (Gebühren, Dezimalstellen, Mindestgrößen). Immer filtern; ungefiltert sind es ~150 Zeilen. |
market book <Symbol> [--limit 20] | Top-of-Book-Gebote und -Briefe. <Symbol> ist der Perp-Ticker (BTC), das Spot-Paar (ETH/USDC) oder der numerische market_index. --limit pro Seite. |
market trades <Symbol> [--limit 20] | Letzte Abschlüsse für einen Markt. --limit max. 100. |
market candles <Symbol> --resolution 1h --count_back 24 | OHLCV-Kerzen. Auflösungen: 1m, 5m, 15m, 30m, 1h, 4h, 1d. Gibt o/h/l/c (Preis), v (Basisvolumen), V (Kursvolumen), t (Bucket-Start, ms), i (letzte Trade-ID) zurück. |
market funding [--symbol X] [--market_index N] [--exchange X] | Finanzierungsraten über Handelsplätze hinweg. ~300 Zeilen ungefiltert; übergeben Sie immer --symbol oder --exchange. |
account info [--account_index N] [--by l1_address --value 0x…] [--include_zero_positions] | Kontosuche: Salden, Positionen, Assets. Standardmäßig wird LIGHTER_ACCOUNT_INDEX verwendet. Verwenden Sie --by l1_address --value …, um stattdessen nach der L1-Adresse zu suchen. positions[] ist standardmäßig auf aktuell offene Positionen gefiltert – Lighter behält eine Zeile pro Markt bei, den das Konto jemals berührt hat, sodass die rohe Liste riesig und größtenteils flach sein kann. Übergeben Sie --include_zero_positions, wenn Sie realized_pnl / total_funding_paid_out pro Markt über die gesamte Lebensdauer benötigen (PnL-Analysen, Funding-Audits, Steuerberichte). |
account apikeys [--account_index N] [--api_key_index N] | API-Schlüssel für ein Konto auflisten. Lassen Sie --api_key_index weg (Standardwert 255), um alle Schlüssel aufzulisten. |
auth status | Lokale Credentials-Vorprüfung. Gibt auth_capable + Quelle pro Credential zurück. Einmal vor authentifizierten Aufrufen ausführen. |
Kontospezifische Lesezugriffe – erfordern LIGHTER_API_PRIVATE_KEY + LIGHTER_ACCOUNT_INDEX + LIGHTER_API_KEY_INDEX
Diese Endpunkte generieren bei jedem Aufruf ein kurzlebiges Authentifizierungstoken aus Ihren konfigurierten Anmeldeinformationen. Das Authentifizierungstoken ist an LIGHTER_ACCOUNT_INDEX gebunden, daher sind alle vier folgenden Befehle nur für das eigene Konto – sie akzeptieren kein --account_index und es gibt keine Möglichkeit, ein anderes Konto als das abzufragen, dessen privater Schlüssel das Token signiert hat.
| Befehl | Zweck |
|---|---|
account limits | Handelslimits und Stufeninformationen. |
portfolio performance --resolution 1h --count_back 24 | PnL-Diagramm über einen Zeitraum. |
orders open (--symbol X | --market_index N) | Offene Orders auf einem Markt. Übergeben Sie entweder --symbol (Perp-Ticker oder Spot-Paar) oder --market_index. |
orders history [--symbol X] [--market_index N] [--limit 20] | Verlauf ausgeführter/stornierter Orders. Der Marktfilter ist optional. |
Plattformhinweis: In der Sandbox-Bash-Umgebung von claude.ai gibt es keine persistente Shell, um Umgebungsvariablen mit
exportzu setzen, und das Einfügen eines privaten API-Schlüssels in den Chat ist nicht akzeptabel. Behandeln Sie die vier obigen Befehle als effektiv nur für Claude Code / Cursor / Desktop. Fallen Sie auf claude.ai auf die öffentlichen Lesezugriffe zurück oder verweisen Sie den Benutzer für kontospezifische Ansichten auf die Lighter-Web-/Mobil-UI.
Gesundheitscheck: python3 scripts/health.py gibt {"status": "ok", "version": "..."} zurück, ohne das SDK zu berühren – nützlich, um zu bestätigen, dass der Skill überhaupt geladen wird.
Vollständige Antwortstrukturen finden Sie unter references/schemas-read.md.
Schreibbefehle (trade.py)
Alle Schreibbefehle erfordern Anmeldeinformationen. Preise und Mengen werden in menschlichen Einheiten angegeben (z. B. --price 4050.5 --amount 0.1); das Skript ruft die Marktmetadaten ab und skaliert sie automatisch auf ganze Ticks/Lose. Die Antwort gibt effective_amount / effective_price zurück, damit Sie sehen können, was nach der Rundung tatsächlich angekommen ist.
Seite akzeptiert beide Formen: --side buy|sell|long|short. Beide werden auf Perp- und Spot-Märkten akzeptiert. Intern auf die kanonische Form normalisiert (long/short für Perp, buy/sell für Spot).
Symbolkonvention: Das positionsbezogene <Symbol>-Argument ist ein Perp-Ticker (BTC, ETH), ein Spot-Paar (ETH/USDC, LIT/USDC) oder ein numerischer market_index (1). Das / in einem Spot-Symbol ist der Unterscheider – kein --market_type-Flag ist erforderlich.
Spot-Handel: Jeder Orderbefehl funktioniert transparent für Spot-Märkte – übergeben Sie einfach ein Spot-Paar wie ETH/USDC. Verwenden Sie query.py market list --market_type spot, um sie zu entdecken. Auf Spot-Märkten sind --reduce_only und die Befehle position leverage / position margin wirkungslos – Spot hat keine gehebelten Positionen.
| Befehl | Wichtige Argumente |
|---|---|
order limit <Symbol> --side <Seite> --amount N --price N [--reduce_only] [--post_only] | Limit-Order auf Perp oder Spot. |
order market <Symbol> --side <Seite> --amount N [--slippage N] [--reduce_only] | Market-Order auf Perp oder Spot. Standard-Slippage 0.01 (1%). |
order modify <Symbol> --order_index COI --price N --amount N | COI ist der client_order_index, der von order limit zurückgegeben wird. |
order cancel <Symbol> --order_index COI | Eine einzelne offene Order stornieren. |
order cancel_all | Alle offenen Orders über alle Märkte hinweg stornieren (keine Argumente). |
order close_all [--slippage N] [--with_cancel_all] [--preview] | Hohes Risiko. Schließt jede offene Position mit Reduce-Only-Marktorders – realisiert PnL auf allen Märkten gleichzeitig. Führen Sie immer zuerst --preview aus und holen Sie die ausdrückliche Zustimmung des Benutzers ein, bevor Sie den eigentlichen Aufruf tätigen; leiten Sie die Absicht nicht automatisch aus Formulierungen wie „aufräumen“ oder „zurücksetzen“ ab. --with_cancel_all tötet auch TP/SL-Klammern. In Kombination mit --preview enthält die Antwort einen Hinweis, dass Cancel-All zuerst ausgeführt würde, aber would_close[] listet dennoch nur die Positionen auf. |
position leverage <Symbol> --leverage N [--margin_mode cross|isolated] | Hebel setzen. Standard cross. |
position margin <Symbol> --amount N --direction add|remove | Der Betrag ist die Bereitstellungssicherheit (USDC oder USDG); nur bei isolierten Positionen gültig. |
account mode --mode classic|unified | Hohes Risiko. Ändert das kontoweite Margin-Verhalten. Überprüfen Sie query.py account info und holen Sie die ausdrückliche Zustimmung des Benutzers ein. |
account collateral --asset A --mode enabled|disabled | Hohes Risiko. Ändert, ob ein berechtigtes Asset im Unified-Modus als Sicherheit beiträgt. Überprüfen Sie das Konto und holen Sie die ausdrückliche Zustimmung des Benutzers ein. |
funds withdraw --asset A --amount N [--route perp|spot] | Standard-Route perp. Akzeptiert jedes Asset-Symbol der Bereitstellung oder eine numerische Asset-ID; collateral aliasiert das Quote-Asset, wenn es eindeutig ist. Dies erstellt eine Auszahlungsanforderung; Gelder können in einen schwebenden/Anspruchs-Fluss übergehen und erscheinen nicht sofort in der Wallet. |
funds transfer --asset A --amount N --from_route perp|spot --to_route perp|spot | Bewegt jedes Asset der Bereitstellung zwischen Ihren eigenen Spot- und Perp-Buckets. Keine L1-Signatur, kein kontenübergreifendes Routing. |
order limit und order market geben einen client_order_index zurück – speichern Sie ihn; er ist der Handle für spätere order modify / order cancel.
Beispiel – Bewegung von Bereitstellungssicherheit von Perp zu Spot, um einen Spot-Kauf zu finanzieren:
python3 scripts/trade.py funds transfer --asset collateral --amount 250 \
--from_route perp --to_route spot
Beispiel – Aktivierung von SPY-Sicherheit auf Robinhood Lighter:
python3 scripts/query.py account info
python3 scripts/trade.py account mode --mode unified
python3 scripts/query.py account info # warten, bis account_trading_mode 1 ist
python3 scripts/trade.py account collateral --asset SPY --mode enabled
python3 scripts/query.py account info
Die beiden obigen Schreibbefehle erfordern eine separate, ausdrückliche Zustimmung des Benutzers. account collateral --mode enabled lehnt Assets ab, die die ausgewählte Bereitstellung nicht als sicherheitsfähig markiert, und lehnt Konten im Classic-Modus ab.
Jeder Befehl unterstützt --help. Das Antwortschema, die Präzisions-Rückmeldung und die Fehlercode-Tabelle finden Sie unter references/schemas-write.md.
Papierhandel (paper.py)
Simulieren Sie Trades anhand echter Lighter-Orderbuch-Schnappschüsse ohne Anmeldeinformationen, ohne Übertragung und ohne Risiko. Der gesamte Zustand ist lokal.
Befehle der gemeinsamen Teilmenge verwenden die <Gruppe> <Aktion>-Form, die mit trade.py identisch ist, sodass das Austauschen des Skriptnamens die Engine austauscht. Nur für den Papierhandel verfügbare Lebenszyklusbefehle bleiben flach.
Befehle
Nur Papierhandel (flach):
| Befehl | Zweck |
|---|---|
init [--collateral N] [--tier T] | Papierkonto erstellen. Standardwerte: --collateral 10000 --tier premium. |
reset [--collateral N] [--tier T] | Zustand zurücksetzen. Die formlose Version verwendet die vorherige Sicherheit und Stufe wieder. |
set_tier --tier T | Gebührenstufe auf einem bestehenden Konto ändern (aktualisiert zwischengespeicherte Marktkonfigurationen). |
status [--no-refresh] | Kontozusammenfassung: Sicherheit, PnL, Positions-/Trade-Anzahl. Aktualisiert automatisch die Marktpreise für alle offenen Positionen; übergeben Sie --no-refresh, um dies zu überspringen. |
positions [--symbol X] [--no-refresh] | Offene Positionen. Ohne --symbol werden alle aufgelistet. Aktualisiert automatisch die Marktpreise. |
trades [--symbol X] [--limit 50] | Trade-Verlauf, die neuesten zuerst. |
health [--no-refresh] | Kontogesundheit: TAV, Margin-Anforderungen, Hebel. Aktualisiert automatisch die Marktpreise. |
liquidation_price <Symbol> [--no-refresh] | Geschätzter Liquidationspreis für eine Position. Aktualisiert automatisch die Marktpreise. |
refresh <Symbol> | Erzwingt die Aktualisierung des Orderbuch-Schnappschusses eines Marktes. Nützlich zum Vorwärmen eines Marktes vor dem Handel oder wenn Sie aktuelle Marktdaten wünschen, ohne bei jedem Lesezugriff --no-refresh zu übergeben. |
Gemeinsame Teilmenge (entspricht der Form von trade.py):
| Befehl | Zweck |
|---|---|
order market <Symbol> --side buy|sell|long|short --amount N | Taker-Marktorder gegen Live-Buch-Schnappschuss. |
order ioc <Symbol> --side buy|sell|long|short --amount N --price N | Taker-IOC-Order mit Limitpreis. |
Austauschregel: Tauschen Sie trade.py ↔ paper.py aus, um ...
[Der Rest wurde für die Übersetzung gekürzt]