Lighter Agent Kit
Opera en Lighter o su implementación en Robinhood Chain usando los mismos comandos.
Los scripts residen en el directorio scripts/ de este skill. Los comandos de lectura usan query.py, los de escritura usan trade.py. Cada comando imprime JSON estructurado a stdout. Los errores siempre están en JSON como {"error": "..."}.
Los comandos usan la sintaxis <grupo> <acción> que refleja la interfaz de Lighter (ej. market stats, order limit, orders open).
Para esquemas de respuesta y detalles, consulta la carpeta references/.
Instalación
Copia esta carpeta a una de las ubicaciones estándar de skills de Claude Code:
- Personal (todos los proyectos):
~/.claude/skills/lighter-agent-kit/ - A nivel de proyecto (solo este repo):
.claude/skills/lighter-agent-kit/
En la primera llamada, lighter-sdk y sus dependencias transitivas se instalarán en <skill>/.vendor/pyX.Y/. Cada versión está fijada por requirements.lock. Los objetivos compatibles son Macs con Apple Silicon y Linux x86_64/arm64. Las Mac con Intel no son compatibles con este kit.
Requiere acceso de red al host de Lighter seleccionado (mainnet.zklighter.elliot.ai, testnet.zklighter.elliot.ai, api.rh.lighter.xyz, o api.rh-testnet.lighter.xyz), pypi.org / files.pythonhosted.org, y github.com (pip clona la compilación fijada de lighter-sdk desde GitHub). En el sandbox de Claude.ai, la lista blanca de salida predeterminada no incluye github.com; deberás ampliarla antes de la primera ejecución.
Los comandos de lectura funcionan sin credenciales. Los comandos de escritura y las lecturas privadas de cuenta verificarán primero las variables de entorno y luego tu archivo de credenciales personal — consulta references/env-vars.md.
Cómo Manejar Solicitudes de Usuario
- Convención de símbolos: perp-desnudo, spot-par. Los mercados perpetuos usan tickers simples (
BTC,ETH,SOL,LIT); los mercados spot usan pares calificados por cotización (ETH/USDCen Lighter,AAPL/USDGen Robinhood Lighter). La presencia de/es el único discriminador — no se necesita la bandera--market_typeen comandos con resolución de símbolos. Elmarket_indexnumérico también se acepta como mecanismo de escape. - La resolución de símbolos es automática. Los símbolos de mercado se resuelven desde la API de libros de órdenes en vivo y se almacenan en caché en disco durante 5 minutos por host, por lo que
query.py,trade.pyypaper.pycomparten el mismo mapa de mercado entre llamadas. Los activos de fondos se resuelven contra la implementación seleccionada;collateralcrea un alias de su activo de cotización cuando no es ambiguo. Solo cuando el usuario dice algo que no puedes mapear con confianza (ej. "petróleo Brent", "oro", "plata"), ejecuta primeropython3 scripts/query.py market list --search <subcadena> [--market_type perp|spot]para descubrirlo. Estos suelen aparecer bajo símbolos tipo ticker comoBRENTOIL,XAUyXAG. - El lado acepta ambas formas.
--side buy|sell|long|short— ambas se aceptan en perpetuos y spot. Normalizado internamente a canónico (long/short para perpetuos, buy/sell para spot). - Filtra en la fuente en lecturas de alta cardinalidad.
market funding,market statsymarket infoaceptan--symbol/--market_index/--exchange— pásalos siempre cuando solo necesites una fila. - Ejecuta el script correspondiente:
python3 scripts/query.py <grupo> <acción> ARGUMENTOSpara lecturas,python3 scripts/trade.py <grupo> <acción> ARGUMENTOSpara escrituras. Las rutas son relativas al directorio de este skill. - Analiza el JSON y preséntalo claramente.
- Comandos con ámbito de cuenta y
LIGHTER_ACCOUNT_INDEX. Dos casos:- Lecturas públicas (
account info,account apikeys) aceptan--account_indexy por defecto usanLIGHTER_ACCOUNT_INDEXcuando se omite. - Lecturas autenticadas (
account limits,portfolio performance,orders open,orders history) son solo para uno mismo usandoLIGHTER_ACCOUNT_INDEXen lugar de--account_indexporque el token de autenticación está vinculado a esa cuenta.
- Lecturas públicas (
Diagnóstico (opcional): si una llamada falla con un error de tipo import lighter, ejecuta python3 scripts/bootstrap.py para verificar que el SDK se haya vendido correctamente. Debería devolver una respuesta con el campo status: ok. Nunca deberías necesitar ejecutar esto en una sesión saludable.
Comandos de Lectura (query.py)
Lecturas públicas — sin credenciales
| Comando | Propósito |
|---|---|
system status | Estado del sistema zkLighter (id de red, timestamp). |
market list [--market_type perp|spot] [--search X] | Catálogo compacto {symbol, market_index, market_type}. Úsalo para búsquedas de símbolo a índice. |
market stats [--symbol X] | Resumen del mercado: precios, volúmenes 24h, operaciones diarias. Pasa --symbol para obtener una sola fila. |
market info [--market_type perp|spot] [--symbol X] | Metadatos completos del mercado (comisiones, decimales, tamaños mínimos). Siempre filtra; sin filtrar son ~150 filas. |
market book <símbolo> [--limit 20] | Ofertas y demandas de la parte superior del libro. <símbolo> es un ticker perpetuo (BTC), un par spot (ETH/USDC) o un market_index numérico. --limit es por lado. |
market trades <símbolo> [--limit 20] | Operaciones recientes completadas en un mercado. --limit máximo 100. |
market candles <símbolo> --resolution 1h --count_back 24 | Velas OHLCV. Resoluciones: 1m, 5m, 15m, 30m, 1h, 4h, 1d. Devuelve o/h/l/c (precio), v (volumen base), V (volumen cotizado), t (inicio del bucket, ms), i (id de la última operación). |
market funding [--symbol X] [--market_index N] [--exchange X] | Tasas de financiación entre plataformas. ~300 filas sin filtrar; pasa siempre --symbol o --exchange. |
account info [--account_index N] [--by l1_address --value 0x…] [--include_zero_positions] | Consulta de cuenta: saldos, posiciones, activos. Por defecto usa LIGHTER_ACCOUNT_INDEX. Usa --by l1_address --value … para buscar por dirección L1. positions[] se filtra a posiciones actualmente abiertas por defecto — Lighter mantiene una fila por mercado que la cuenta haya tocado, por lo que la lista sin procesar puede ser enorme y mayormente plana. Pasa --include_zero_positions cuando necesites realized_pnl / total_funding_paid_out de por vida por mercado (análisis de PnL, auditorías de financiación, informes fiscales). |
account apikeys [--account_index N] [--api_key_index N] | Lista las claves API de una cuenta. Omite --api_key_index (por defecto 255) para listar todas las claves. |
auth status | Verificación previa local de credenciales. Devuelve auth_capable + fuente por credencial. Ejecútalo una vez antes de llamadas autenticadas. |
Lecturas privadas de cuenta — requieren LIGHTER_API_PRIVATE_KEY + LIGHTER_ACCOUNT_INDEX + LIGHTER_API_KEY_INDEX
Estos endpoints generan un token de autenticación de corta duración a partir de tus credenciales configuradas en cada llamada. El token de autenticación está vinculado a LIGHTER_ACCOUNT_INDEX, por lo que los cuatro comandos siguientes son solo para uno mismo — no aceptan --account_index y no hay forma de consultar una cuenta diferente de aquella cuya clave privada firmó el token.
| Comando | Propósito |
|---|---|
account limits | Límites de negociación e información de nivel. |
portfolio performance --resolution 1h --count_back 24 | Gráfico de PnL durante un período de tiempo. |
orders open (--symbol X | --market_index N) | Órdenes abiertas en un mercado. Pasa --symbol (ticker perpetuo o par spot) o --market_index. |
orders history [--symbol X] [--market_index N] [--limit 20] | Historial de órdenes completadas / canceladas. El filtro de mercado es opcional. |
Nota de plataforma: en el entorno bash limitado de claude.ai no hay un shell persistente para
exportar variables de entorno, y pegar una clave privada de API en el chat no es aceptable. Trata los cuatro comandos anteriores como efectivamente solo para Claude Code / Cursor / escritorio. En claude.ai, recurre a las lecturas públicas o dirige al usuario a la interfaz web/móvil de Lighter para vistas privadas de cuenta.
Verificación de integridad: python3 scripts/health.py devuelve {"status": "ok", "version": "..."} sin tocar el SDK — útil para confirmar que el skill se carga correctamente.
Consulta references/schemas-read.md para las formas completas de las respuestas.
Comandos de Escritura (trade.py)
Todos los comandos de escritura requieren credenciales. Los precios y cantidades están en unidades humanas (ej. --price 4050.5 --amount 0.1); el script obtiene los metadatos del mercado y los escala automáticamente a ticks/lotes enteros. La respuesta repite effective_amount / effective_price para que puedas ver lo que realmente se registró después del redondeo.
El lado acepta ambas formas: --side buy|sell|long|short. Ambas se aceptan en mercados perpetuos y spot. Normalizado internamente a canónico (long/short para perpetuos, buy/sell para spot).
Convención de símbolos: El argumento posicional <símbolo> es un ticker perpetuo (BTC, ETH), un par spot (ETH/USDC, LIT/USDC), o un market_index numérico (1). La / en un símbolo spot es el discriminador — no se necesita la bandera --market_type.
Negociación spot: cada comando de órdenes funciona de forma transparente para mercados spot — solo pasa un par spot como ETH/USDC. Usa query.py market list --market_type spot para descubrirlos. En mercados spot, --reduce_only y los comandos position leverage / position margin no tienen efecto — el spot no tiene posiciones apalancadas.
| Comando | Argumentos clave |
|---|---|
order limit <símbolo> --side <lado> --amount N --price N [--reduce_only] [--post_only] | Orden limitada en perpetuos o spot. |
order market <símbolo> --side <lado> --amount N [--slippage N] [--reduce_only] | Orden de mercado en perpetuos o spot. Deslizamiento predeterminado 0.01 (1%). |
order modify <símbolo> --order_index COI --price N --amount N | COI es el client_order_index devuelto por order limit. |
order cancel <símbolo> --order_index COI | Cancela una sola orden abierta. |
order cancel_all | Cancela todas las órdenes abiertas en todos los mercados (sin argumentos). |
order close_all [--slippage N] [--with_cancel_all] [--preview] | Alto riesgo. Liquida todas las posiciones abiertas con órdenes de mercado de reducción única — realiza PnL en todos los mercados a la vez. Ejecuta siempre --preview primero y obtén la aprobación explícita del usuario antes de la llamada real; no infieras automáticamente la intención de frases como "limpiar" o "reiniciar". --with_cancel_all también elimina los brackets TP/SL. Cuando se combina con --preview, la respuesta incluye una nota de que cancel-all se ejecutaría primero, pero would_close[] aún solo enumera las posiciones. |
position leverage <símbolo> --leverage N [--margin_mode cross|isolated] | Establece el apalancamiento. Por defecto cross. |
position margin <símbolo> --amount N --direction add|remove | La cantidad es colateral de la implementación (USDC o USDG); solo válido en posiciones aisladas. |
account mode --mode classic|unified | Alto riesgo. Cambia el comportamiento del margen en toda la cuenta. Inspecciona query.py account info y obtén la aprobación explícita del usuario primero. |
account collateral --asset A --mode enabled|disabled | Alto riesgo. Cambia si un activo elegible contribuye como colateral en modo Unified. Inspecciona la cuenta y obtén la aprobación explícita del usuario primero. |
funds withdraw --asset A --amount N [--route perp|spot] | Ruta predeterminada perp. Acepta cualquier símbolo de activo de la implementación o ID de activo numérico; collateral crea un alias del activo de cotización cuando no es ambiguo. Esto crea una solicitud de retiro; los fondos pueden pasar a un flujo pendiente/reclamación y no aparecer instantáneamente en la billetera. |
funds transfer --asset A --amount N --from_route perp|spot --to_route perp|spot | Mueve cualquier activo de la implementación entre tus buckets spot y perpetuos. Sin firma L1, sin enrutamiento entre cuentas. |
order limit y order market devuelven un client_order_index — guárdalo; es el identificador para posteriores order modify / order cancel.
Ejemplo — mover colateral de la implementación de perpetuos a spot para financiar una compra spot:
python3 scripts/trade.py funds transfer --asset collateral --amount 250 \
--from_route perp --to_route spot
Ejemplo — habilitar colateral SPY en Robinhood Lighter:
python3 scripts/query.py account info
python3 scripts/trade.py account mode --mode unified
python3 scripts/query.py account info # espera hasta que account_trading_mode sea 1
python3 scripts/trade.py account collateral --asset SPY --mode enabled
python3 scripts/query.py account info
Los dos comandos de escritura anteriores requieren aprobación explícita separada del usuario. account collateral --mode enabled rechaza activos que la implementación seleccionada no marca como elegibles para colateral y rechaza cuentas en modo Classic.
Cada comando admite --help. Consulta references/schemas-write.md para la envoltura de respuesta, eco de precisión y tabla de códigos de error.
Paper Trading (paper.py)
Simula operaciones contra instantáneas reales del libro de órdenes de Lighter sin credenciales, sin transmitir y sin riesgo. Todo el estado es local.
Los comandos del subconjunto compartido usan la forma <grupo> <acción> idéntica a trade.py, por lo que intercambiar el nombre del script intercambia el motor. Los comandos de ciclo de vida exclusivos de paper permanecen planos.
Comandos
Solo paper (planos):
| Comando | Propósito |
|---|---|
init [--collateral N] [--tier T] | Crea una cuenta de paper. Valores predeterminados: --collateral 10000 --tier premium. |
reset [--collateral N] [--tier T] | Borra el estado. La forma sin argumentos reutiliza el colateral y nivel anteriores. |
set_tier --tier T | Cambia el nivel de comisiones en una cuenta existente (actualiza las configuraciones de mercado en caché). |
status [--no-refresh] | Resumen de cuenta: colateral, PnL, recuentos de posiciones/operaciones. Actualiza automáticamente los precios de marca para todas las posiciones abiertas; pasa --no-refresh para omitir. |
positions [--symbol X] [--no-refresh] | Posiciones abiertas. Sin --symbol lista todas. Actualiza automáticamente los precios de marca. |
trades [--symbol X] [--limit 50] | Historial de operaciones, más recientes primero. |
health [--no-refresh] | Salud de la cuenta: TAV, requisitos de margen, apalancamiento. Actualiza automáticamente los precios de marca. |
liquidation_price <símbolo> [--no-refresh] | Precio de liquidación estimado para una posición. Actualiza automáticamente los precios de marca. |
refresh <símbolo> | Fuerza la actualización de la instantánea del libro de órdenes de un mercado. Útil para precalentar un mercado antes de operar, o cuando deseas datos de marca actuales sin pasar --no-refresh en cada lectura. |
Subconjunto compartido (refleja la forma de trade.py):
| Comando | Propósito |
|---|---|
order market <símbolo> --side buy|sell|long|short --amount N | Orden de mercado tomadora contra una instantánea del libro en vivo. |
order ioc <símbolo> --side buy|sell|long|short --amount N --price N | Orden IOC tomadora con precio límite. |
Regla de intercambio: intercambia trade.py ↔ paper.py para cambiar entre operaciones reales y simuladas. Todos los comandos compartidos son idénticos en forma.
Ejemplo:
python3 scripts/paper.py init --collateral 50000 --tier premium
python3 scripts/paper.py order market ETH --side long --amount 0.5
python3 scripts/paper.py status
Consulta references/schemas-paper.md para el diseño del estado simulado y esquemas de respuesta.
Referencias
Documentos de apoyo en references/:
| Archivo | Contenido |
|---|---|
| references/env-vars.md | Variables de entorno (credenciales, host de la cadena, configuración de cuenta). |
| references/schemas-read.md | Esquemas de respuesta de query.py, modos de error. |
| references/schemas-write.md | Esquemas de respuesta de trade.py, envoltura de eco. |
| references/schemas-paper.md | Diseño del estado interno de paper.py. |
| references/schemas-failures.md | Patrones de error comunes y códigos de error. |
Solución de Problemas
"import lighter" falla. Ejecuta python3 scripts/bootstrap.py. Si devuelve status: ok, el SDK está vendido; el problema está en otra parte. De lo contrario, verifica tu conexión de red y que tu plataforma sea compatible.
"No module named 'requests'" / "No module named 'websockets'". La instalación de dependencias falló. Ejecuta python3 scripts/bootstrap.py para reintentar.
No se puede conectar al host. Verifica que la URL del host sea accesible. Lighter requiere puertos 443 (wss). curl -v https://mainnet.zklighter.elliot.ai/health debería devolver un JSON.
"Not authenticated" en un comando de escritura. Verifica que LIGHTER_API_PRIVATE_KEY esté configurada y coincida con LIGHTER_ACCOUNT_INDEX. Ejecuta python3 scripts/query.py auth status para diagnosticar.
La resolución de símbolos produce "cannot map symbol". Pide al usuario el nombre exacto del ticker o el par. Ejecuta python3 scripts/query.py market list --search <subcadena> [--market_type perp|spot] para descubrir la forma correcta.
El saldo del colateral parece bajo. En modo Unified, los activos no marcados como colateral no contribuyen. Ejecuta python3 scripts/query.py account info e inspecciona el array assets[]: cada entrada tiene .collateral_enabled en modo Unified. Para activos spot, el colateral spot debe transferirse al bucket de perpetuos con funds transfer --from_route spot --to_route perp.