elliottech/lighter-agent-kit

Lighter Agent Kit

Tradez sur Lighter ou son déploiement Robinhood Chain en utilisant les mêmes commandes.

Les scripts se trouvent dans le répertoire scripts/ de cette compétence. Les commandes de lecture utilisent query.py, les commandes d'écriture utilisent trade.py. Chaque commande imprime du JSON structuré sur stdout. Les erreurs sont toujours en JSON sous la forme {"error": "..."}.

Les commandes utilisent la syntaxe <groupe> <action> qui reflète l'interface utilisateur de Lighter (par exemple market stats, order limit, orders open).

Pour les schémas de réponse et les détails, consultez le dossier references/.

Installation

Copiez ce dossier dans l'un des emplacements standards des compétences Claude Code :

• Personnel (tous les projets) : ~/.claude/skills/lighter-agent-kit/
• Au niveau du projet (ce dépôt uniquement) : .claude/skills/lighter-agent-kit/

Lors du premier appel, lighter-sdk et ses dépendances transitives seront installés dans <skill>/.vendor/pyX.Y/. Chaque version est épinglée par requirements.lock. Les cibles supportées sont les Mac Apple Silicon ainsi que Linux x86_64/arm64. Les Mac Intel ne sont pas supportés par ce kit.

Nécessite un accès réseau sortant vers l'hôte Lighter sélectionné (mainnet.zklighter.elliot.ai, testnet.zklighter.elliot.ai, api.rh.lighter.xyz, ou api.rh-testnet.lighter.xyz), pypi.org / files.pythonhosted.org, et github.com (pip clone la version épinglée de lighter-sdk depuis GitHub). Dans le bac à sable de Claude.ai, la liste d'autorisation de trafic sortant par défaut n'inclut pas github.com — vous devrez l'étendre avant la première exécution.

Les commandes de lecture fonctionnent sans informations d'identification. Les commandes d'écriture et les lectures privées du compte vérifieront d'abord les variables d'environnement, puis votre fichier d'informations d'identification personnel — voir references/env-vars.md.

Comment Gérer les Demandes des Utilisateurs

1. Convention de symbole : perp-bare, spot-pair. Les marchés perp utilisent des tickers simples (BTC, ETH, SOL, LIT) ; les marchés spot utilisent des paires avec guillemet (ETH/USDC sur Lighter, AAPL/USDG sur Robinhood Lighter). La présence de / est le seul discriminant — aucun indicateur --market_type n'est nécessaire sur les commandes résolues par symbole. L'index de marché numérique market_index est également accepté comme échappatoire.
2. La résolution des symboles est automatique. Les symboles de marché sont résolus à partir de l'API des carnets d'ordres en direct et sont mis en cache sur le disque pendant 5 minutes par hôte, de sorte que query.py, trade.py et paper.py partagent la même carte des marchés entre les appels. Les actifs du fonds sont résolus par rapport au déploiement sélectionné ; collateral fait référence à l'actif de cotation lorsqu'il est sans ambiguïté. Uniquement lorsque l'utilisateur dit quelque chose que vous ne pouvez pas mapper avec certitude (par exemple « pétrole brut », « or », « argent »), exécutez d'abord python3 scripts/query.py market list --search <sous-chaîne> [--market_type perp|spot] pour le découvrir. Ceux-ci apparaissent généralement sous des symboles de type ticker comme BRENTOIL, XAU et XAG.
3. Le côté accepte les deux formes. --side buy|sell|long|short — les deux sont acceptés sur les marchés perp et spot. Normalisé en interne en canonique (long/short pour perp, buy/sell pour spot).
4. Filtrez à la source sur les lectures à haute cardinalité. market funding, market stats et market info acceptent --symbol / --market_index / --exchange — passez-les toujours lorsque vous n'avez besoin que d'une seule ligne.
5. Exécutez le script correspondant : python3 scripts/query.py <groupe> <action> ARGS pour les lectures, python3 scripts/trade.py <groupe> <action> ARGS pour les écritures. Les chemins sont relatifs au répertoire de cette compétence.
6. Analysez le JSON et présentez-le clairement.
7. Commandes liées au compte et LIGHTER_ACCOUNT_INDEX. Deux cas :
   • Lectures publiques (account info, account apikeys) acceptent --account_index et utilisent par défaut LIGHTER_ACCOUNT_INDEX lorsqu'il est omis.
   • Lectures authentifiées (account limits, portfolio performance, orders open, orders history) sont auto-uniquement en utilisant LIGHTER_ACCOUNT_INDEX au lieu de --account_index car le jeton d'authentification est lié à ce compte.

Diagnostic (facultatif) : si un appel échoue avec une erreur de type import lighter, exécutez python3 scripts/bootstrap.py pour vérifier que le SDK a été correctement vendu. Il devrait renvoyer une réponse avec le champ status : ok. Vous ne devriez jamais avoir besoin d'exécuter cela dans une session saine.

---

Commandes de Lecture (query.py)

Lectures publiques — aucune information d'identification

Commande	Objectif
system status	Statut du système zkLighter (identifiant réseau, horodatage).
market list [--market_type perp|spot] [--search X]	Catalogue compact {symbol, market_index, market_type}. Utilisez pour les recherches symbole → index.
market stats [--symbol X]	Aperçu du marché : prix, volumes 24h, transactions quotidiennes. Passez --symbol pour obtenir une seule ligne.
market info [--market_type perp|spot] [--symbol X]	Métadonnées complètes du marché (frais, décimales, tailles minimales). Filtrez toujours ; non filtré, c'est ~150 lignes.
market book <symbole> [--limit 20]	Offres et demandes de premier plan. <symbole> est le ticker perp (BTC), la paire spot (ETH/USDC) ou l'index de marché numérique. --limit est par côté.
market trades <symbole> [--limit 20]	Exécutions récentes pour un marché. --limit max 100.
market candles <symbole> --resolution 1h --count_back 24	Bougies OHLCV. Résolutions : 1m, 5m, 15m, 30m, 1h, 4h, 1d. Renvoie o/h/l/c (prix), v (volume de base), V (volume de cotation), t (début de la bougie, ms), i (dernier identifiant de transaction).
market funding [--symbol X] [--market_index N] [--exchange X]	Taux de financement entre plateformes. ~300 lignes non filtrées ; passez toujours --symbol ou --exchange.
account info [--account_index N] [--by l1_address --value 0x…] [--include_zero_positions]	Consultation du compte : soldes, positions, actifs. Utilise par défaut LIGHTER_ACCOUNT_INDEX. Utilisez --by l1_address --value … pour rechercher par adresse L1. positions[] est filtré par défaut sur les positions actuellement ouvertes — Lighter conserve une ligne par marché que le compte a jamais touché, donc la liste brute peut être énorme et surtout plate. Passez --include_zero_positions lorsque vous avez besoin de realized_pnl / total_funding_paid_out par marché (analyses PnL, audits de financement, rapports fiscaux).
account apikeys [--account_index N] [--api_key_index N]	Liste des clés API pour un compte. Omettre --api_key_index (valeur par défaut 255) pour lister toutes les clés.
auth status	Pré-vérification locale des informations d'identification. Renvoie auth_capable + source par information d'identification. Exécutez une fois avant les appels authentifiés.

Lectures privées du compte — nécessitent LIGHTER_API_PRIVATE_KEY + LIGHTER_ACCOUNT_INDEX + LIGHTER_API_KEY_INDEX

Ces points de terminaison génèrent un jeton d'authentification de courte durée à partir de vos informations d'identification configurées à chaque appel. Le jeton d'authentification est lié à LIGHTER_ACCOUNT_INDEX, donc les quatre commandes ci-dessous sont auto-uniquement — elles n'acceptent pas --account_index et il n'y a aucun moyen d'interroger un compte différent de celui dont la clé privée a signé le jeton.

Commande	Objectif
account limits	Limites de trading et informations sur le niveau.
portfolio performance --resolution 1h --count_back 24	Graphique PnL sur une plage de temps.
orders open (--symbol X | --market_index N)	Ordres ouverts sur un marché. Passez soit --symbol (ticker perp ou paire spot) soit --market_index.
orders history [--symbol X] [--market_index N] [--limit 20]	Historique des ordres exécutés/annulés. Le filtre de marché est facultatif.

Note sur la plateforme : sur l'environnement bash en bac à sable de claude.ai il n'y a pas de shell persistant pour export les variables d'environnement, et coller une clé privée API dans le chat n'est pas acceptable. Traitez les quatre commandes ci-dessus comme étant effectivement réservées à Claude Code / Cursor / bureau. Sur claude.ai, revenez aux lectures publiques ou dirigez l'utilisateur vers l'interface utilisateur Web/mobile de Lighter pour les vues privées du compte.

Vérification de santé : python3 scripts/health.py renvoie {"status": "ok", "version": "..."} sans toucher au SDK — utile pour confirmer que la compétence se charge.

Voir references/schemas-read.md pour les formes complètes des réponses.

---

Commandes d'Écriture (trade.py)

Toutes les commandes d'écriture nécessitent des informations d'identification. Les prix et les montants sont en unités humaines (par exemple --price 4050.5 --amount 0.1) ; le script récupère les métadonnées du marché et les convertit automatiquement en ticks/lots entiers. La réponse renvoie effective_amount / effective_price afin que vous puissiez voir ce qui a réellement été appliqué après l'arrondi.

Le côté accepte les deux formes : --side buy|sell|long|short. Les deux sont acceptés sur les marchés perp et spot. Normalisé en interne en canonique (long/short pour perp, buy/sell pour spot).

Convention de symbole : L'argument positionnel <symbole> est un ticker perp (BTC, ETH), une paire spot (ETH/USDC, LIT/USDC) ou un index de marché numérique (1). Le / dans un symbole spot est le discriminant — aucun indicateur --market_type n'est nécessaire.

Trading spot : chaque commande d'ordre fonctionne de manière transparente pour les marchés spot — passez simplement une paire spot comme ETH/USDC. Utilisez query.py market list --market_type spot pour les découvrir. Sur les marchés spot, --reduce_only et les commandes position leverage / position margin sont sans effet — le spot n'a pas de positions à effet de levier.

Commande	Arguments clés
order limit <symbole> --side <côté> --amount N --price N [--reduce_only] [--post_only]	Ordre limité sur perp ou spot.
order market <symbole> --side <côté> --amount N [--slippage N] [--reduce_only]	Ordre au marché sur perp ou spot. Slippage par défaut 0.01 (1%).
order modify <symbole> --order_index COI --price N --amount N	COI est le client_order_index renvoyé par order limit.
order cancel <symbole> --order_index COI	Annuler un seul ordre ouvert.
order cancel_all	Annuler tous les ordres ouverts sur tous les marchés (aucun argument).
order close_all [--slippage N] [--with_cancel_all] [--preview]	Risque élevé. Ferme toutes les positions ouvertes avec des ordres au marché de réduction uniquement — réalise le PnL sur tous les marchés à la fois. Exécutez toujours --preview d'abord et obtenez une approbation explicite de l'utilisateur avant l'appel réel ; n'inférez pas automatiquement l'intention à partir de phrases comme « nettoyer » ou « réinitialiser ». --with_cancel_all supprime également les brackets TP/SL. Lorsqu'il est combiné avec --preview, la réponse inclut une note indiquant que cancel-all s'exécuterait en premier, mais would_close[] liste toujours uniquement les positions.
position leverage <symbole> --leverage N [--margin_mode cross|isolated]	Définir l'effet de levier. Par défaut cross.
position margin <symbole> --amount N --direction add|remove	Le montant est la garantie de déploiement (USDC ou USDG) ; valide uniquement sur les positions isolées.
account mode --mode classic|unified	Risque élevé. Modifie le comportement de la marge à l'échelle du compte. Inspectez query.py account info et obtenez une approbation explicite de l'utilisateur d'abord.
account collateral --asset A --mode enabled|disabled	Risque élevé. Modifie si un actif éligible contribue à la garantie en mode Unifié. Inspectez le compte et obtenez une approbation explicite de l'utilisateur d'abord.
funds withdraw --asset A --amount N [--route perp|spot]	Route par défaut perp. Accepte tout symbole d'actif de déploiement ou ID d'actif numérique ; collateral fait référence à l'actif de cotation lorsqu'il est sans ambiguïté. Cela crée une demande de retrait ; les fonds peuvent entrer dans un flux en attente / de réclamation et ne pas apparaître instantanément dans le portefeuille.
funds transfer --asset A --amount N --from_route perp|spot --to_route perp|spot	Déplace tout actif de déploiement entre vos propres compartiments spot et perp. Aucune signature L1, aucun routage inter-compte.

order limit et order market renvoient un client_order_index — conservez-le ; c'est la référence pour les commandes ultérieures order modify / order cancel.

Exemple — déplacer la garantie de déploiement du perp vers le spot pour financer un achat au comptant :

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

Exemple — activer la garantie SPY sur Robinhood Lighter :

python3 scripts/query.py account info
python3 scripts/trade.py account mode --mode unified
python3 scripts/query.py account info  # attendre que account_trading_mode soit 1
python3 scripts/trade.py account collateral --asset SPY --mode enabled
python3 scripts/query.py account info

Les deux commandes d'écriture ci-dessus nécessitent une approbation distincte et explicite de l'utilisateur. account collateral --mode enabled rejette les actifs que le déploiement sélectionné ne marque pas comme éligibles à la garantie et rejette les comptes en mode Classique.

Chaque commande supporte --help. Voir references/schemas-write.md pour l'enveloppe de réponse, l'écho de précision et le tableau des codes d'erreur.

---

Trading sur Papier (paper.py)

Simulez des transactions par rapport à des instantanés réels du carnet d'ordres de Lighter sans informations d'identification, sans diffusion et sans risque. Tout l'état est local.

Les commandes du sous-ensemble partagé utilisent la forme <groupe> <action> identique à trade.py, donc échanger le nom du script échange le moteur. Les commandes de cycle de vie propres au papier restent plates.

Commandes

Propres au papier (plates) :

Commande	Objectif
init [--collateral N] [--tier T]	Créer un compte papier. Par défaut : --collateral 10000 --tier premium.
reset [--collateral N] [--tier T]	Effacer l'état. La forme sans arguments réutilise la garantie et le niveau précédents.
set_tier --tier T	Modifier le niveau de frais sur un compte existant (met à jour les configurations de marché mises en cache).
status [--no-refresh]	Résumé du compte : garantie, PnL, nombre de positions/transactions. Actualise automatiquement les prix de marque pour toutes les positions ouvertes ; passez --no-refresh pour ignorer.
positions [--symbol X] [--no-refresh]	Positions ouvertes. Sans --symbol, liste toutes. Actualise automatiquement les prix de marque.
trades [--symbol X] [--limit 50]	Historique des transactions, la plus récente en premier.
health [--no-refresh]	Santé du compte : VAM, exigences de marge, effet de levier. Actualise automatiquement les prix de marque.
liquidation_price <symbole> [--no-refresh]	Prix de liquidation estimé pour une position. Actualise automatiquement les prix de marque.
refresh <symbole>	Forcer l'actualisation de l'instantané du carnet d'ordres d'un marché. Utile pour préchauffer un marché avant de trader, ou lorsque vous souhaitez des données de marque actuelles sans passer --no-refresh à chaque lecture.

Sous-ensemble partagé (reflète la forme de trade.py) :

Commande	Objectif
order market <symbole> --side buy|sell|long|short --amount N	Ordre au marché preneur sur un instantané de carnet en direct.
order ioc <symbole> --side buy|sell|long|short --amount N --price N	Ordre IOC preneur avec prix limite.

Règle d'échange : échangez trade.py ↔ paper.py pour