Lighter Agent Kit
Negocie na Lighter ou em sua implantação na Robinhood Chain usando os mesmos comandos.
Os scripts residem no diretório scripts/ desta skill. Comandos de leitura usam query.py, comandos de escrita usam trade.py. Cada comando imprime JSON estruturado no stdout. Erros são sempre em JSON no formato {"error": "..."}.
Os comandos usam a sintaxe <grupo> <ação> que espelha a interface da Lighter (ex: market stats, order limit, orders open).
Para esquemas de resposta e detalhes, veja a pasta references/.
Instalação
Copie esta pasta para um dos locais padrão de skills do Claude Code:
- Pessoal (todos os projetos):
~/.claude/skills/lighter-agent-kit/ - Nível de projeto (apenas este repositório):
.claude/skills/lighter-agent-kit/
Na primeira chamada, lighter-sdk e suas dependências transitivas serão instaladas em <skill>/.vendor/pyX.Y/. Cada versão é fixada pelo requirements.lock. Os alvos suportados são Macs com Apple Silicon e Linux x86_64/arm64. Macs Intel não são suportados por este kit.
Requer saída de rede para o host Lighter selecionado (mainnet.zklighter.elliot.ai, testnet.zklighter.elliot.ai, api.rh.lighter.xyz, ou api.rh-testnet.lighter.xyz), pypi.org / files.pythonhosted.org, e github.com (pip clona o build fixado do lighter-sdk do GitHub). No sandbox do Claude.ai, a lista de permissão de saída padrão não inclui github.com — você precisará expandi-la antes da primeira execução.
Comandos de leitura funcionam sem credenciais. Comandos de escrita e leituras privadas da conta primeiro verificarão as variáveis de ambiente e, em seguida, seu arquivo de credenciais pessoal — veja references/env-vars.md.
Como Lidar com Solicitações do Usuário
- Convenção de símbolos: perp-bare, spot-pair. Mercados perpétuos usam tickers simples (
BTC,ETH,SOL,LIT); mercados spot usam pares com cotação (ETH/USDCna Lighter,AAPL/USDGna Robinhood Lighter). A presença de/é o único discriminador — nenhuma flag--market_typeé necessária em comandos que resolvem símbolos. Omarket_indexnumérico também é aceito como alternativa. - A resolução de símbolos é automática. Os símbolos de mercado são resolvidos a partir da API de orderbooks ativos e armazenados em cache em disco por 5 minutos por host, para que
query.py,trade.pyepaper.pycompartilhem o mesmo mapa de mercados nas chamadas. Os ativos de fundos são resolvidos em relação à implantação selecionada;collateralé um alias para o ativo de cotação quando não ambíguo. Somente quando o usuário disser algo que você não consegue mapear com confiança (ex: "brent oil", "gold", "silver"), executepython3 scripts/query.py market list --search <substring> [--market_type perp|spot]primeiro para descobrir. Esses geralmente aparecem com símbolos no estilo ticker, comoBRENTOIL,XAUeXAG. - O lado aceita ambas as formas.
--side buy|sell|long|short— ambos são aceitos em perp e spot. Normalizado internamente para o canônico (long/short para perp, buy/sell para spot). - Filtre na fonte em leituras de alta cardinalidade.
market funding,market statsemarket infoaceitam--symbol/--market_index/--exchange— sempre passe-os quando precisar de apenas uma linha. - Execute o script correspondente:
python3 scripts/query.py <grupo> <ação> ARGSpara leituras,python3 scripts/trade.py <grupo> <ação> ARGSpara escritas. Os caminhos são relativos ao diretório desta skill. - Analise o JSON e apresente-o claramente.
- Comandos com escopo de conta e
LIGHTER_ACCOUNT_INDEX. Dois casos:- Leituras públicas (
account info,account apikeys) aceitam--account_indexe usamLIGHTER_ACCOUNT_INDEXcomo padrão quando omitido. - Leituras autenticadas (
account limits,portfolio performance,orders open,orders history) são auto-serviço usandoLIGHTER_ACCOUNT_INDEXem vez de--account_indexporque o token de autenticação está vinculado a essa conta.
- Leituras públicas (
Diagnóstico (opcional): se uma chamada falhar com um erro do tipo import lighter, execute python3 scripts/bootstrap.py para verificar se o SDK foi instalado corretamente. Deve retornar uma resposta com o campo status: ok. Você nunca deve precisar executar isso em uma sessão saudável.
Comandos de Leitura (query.py)
Leituras públicas — sem credenciais
| Comando | Propósito |
|---|---|
system status | Status do sistema zkLighter (id da rede, timestamp). |
market list [--market_type perp|spot] [--search X] | Catálogo compacto {symbol, market_index, market_type}. Use para buscas de símbolo → índice. |
market stats [--symbol X] | Visão geral do mercado: preços, volumes 24h, negociações diárias. Passe --symbol para obter uma linha. |
market info [--market_type perp|spot] [--symbol X] | Metadados completos do mercado (taxas, decimais, tamanhos mínimos). Sempre filtre; sem filtro são ~150 linhas. |
market book <symbol> [--limit 20] | Topo do livro de ofertas de compra e venda. <symbol> é o ticker perp (BTC), par spot (ETH/USDC), ou market_index numérico. --limit é por lado. |
market trades <symbol> [--limit 20] | Negociações recentes para um mercado. --limit máximo 100. |
market candles <symbol> --resolution 1h --count_back 24 | Velas OHLCV. Resoluções: 1m, 5m, 15m, 30m, 1h, 4h, 1d. Retorna o/h/l/c (preço), v (volume base), V (volume de cotação), t (início do bucket, ms), i (último id de negociação). |
market funding [--symbol X] [--market_index N] [--exchange X] | Taxas de funding entre plataformas. ~300 linhas sem filtro; sempre passe --symbol ou --exchange. |
account info [--account_index N] [--by l1_address --value 0x…] [--include_zero_positions] | Consulta de conta: saldos, posições, ativos. Usa como padrão LIGHTER_ACCOUNT_INDEX. Use --by l1_address --value … para consultar por endereço L1. positions[] é filtrado para posições atualmente abertas por padrão — a Lighter mantém uma linha por mercado que a conta já tocou, então a lista bruta pode ser enorme e quase toda plana. Passe --include_zero_positions quando precisar de realized_pnl / total_funding_paid_out vitalícios por mercado (análise de PnL, auditorias de funding, relatórios fiscais). |
account apikeys [--account_index N] [--api_key_index N] | Lista de chaves de API para uma conta. Omita --api_key_index (padrão 255) para listar todas as chaves. |
auth status | Pré-verificação local de credenciais. Retorna auth_capable + origem por credencial. Execute uma vez antes de chamadas autenticadas. |
Leituras privadas da conta — requerem LIGHTER_API_PRIVATE_KEY + LIGHTER_ACCOUNT_INDEX + LIGHTER_API_KEY_INDEX
Esses endpoints geram um token de autenticação de curta duração a partir das credenciais configuradas em cada chamada. O token de autenticação está vinculado a LIGHTER_ACCOUNT_INDEX, portanto todos os quatro comandos abaixo são auto-serviço — eles não aceitam --account_index e não há como consultar uma conta diferente daquela cuja chave privada assinou o token.
| Comando | Propósito |
|---|---|
account limits | Limites de negociação e informações de nível. |
portfolio performance --resolution 1h --count_back 24 | Gráfico de PnL ao longo de um intervalo de tempo. |
orders open (--symbol X | --market_index N) | Ordens abertas em um mercado. Passe --symbol (ticker perp ou par spot) ou --market_index. |
orders history [--symbol X] [--market_index N] [--limit 20] | Histórico de ordens executadas/canceladas. O filtro de mercado é opcional. |
Nota de plataforma: no ambiente de bash isolado do claude.ai não há um shell persistente para
exportarvariáveis de ambiente, e colar uma chave privada de API no chat não é aceitável. Trate os quatro comandos acima como efetivamente apenas para Claude Code / Cursor / desktop. No claude.ai, recorra a leituras públicas ou direcione o usuário para a interface web/mobile da Lighter para visualizações privadas da conta.
Verificação de integridade: python3 scripts/health.py retorna {"status": "ok", "version": "..."} sem tocar no SDK — útil para confirmar que a skill carrega.
Veja references/schemas-read.md para os formatos completos de resposta.
Comandos de Escrita (trade.py)
Todos os comandos de escrita requerem credenciais. Preços e quantidades estão em unidades humanas (ex: --price 4050.5 --amount 0.1); o script busca os metadados do mercado e os escala automaticamente para ticks/lotes inteiros. A resposta ecoa effective_amount / effective_price para que você veja o que realmente foi aplicado após o arredondamento.
O lado aceita ambas as formas: --side buy|sell|long|short. Ambos são aceitos em mercados perp e spot. Normalizado internamente para o canônico (long/short para perp, buy/sell para spot).
Convenção de símbolos: o argumento posicional <symbol> é um ticker perp (BTC, ETH), um par spot (ETH/USDC, LIT/USDC), ou um market_index numérico (1). A / em um símbolo spot é o discriminador — nenhuma flag --market_type é necessária.
Negociação spot: cada comando de ordem funciona de forma transparente para mercados spot — basta passar um par spot como ETH/USDC. Use query.py market list --market_type spot para descobri-los. Em mercados spot, --reduce_only e os comandos position leverage / position margin são inócuos — spot não tem posições alavancadas.
| Comando | Argumentos-chave |
|---|---|
order limit <symbol> --side <side> --amount N --price N [--reduce_only] [--post_only] | Ordem limit em perp ou spot. |
order market <symbol> --side <side> --amount N [--slippage N] [--reduce_only] | Ordem market em perp ou spot. Slippage padrão 0.01 (1%). |
order modify <symbol> --order_index COI --price N --amount N | COI é o client_order_index retornado por order limit. |
order cancel <symbol> --order_index COI | Cancela uma ordem aberta. |
order cancel_all | Cancela todas as ordens abertas em todos os mercados (sem argumentos). |
order close_all [--slippage N] [--with_cancel_all] [--preview] | Alto risco. Fecha todas as posições abertas com ordens market reduce-only — realiza PnL em todos os mercados de uma vez. Sempre execute --preview primeiro e obtenha aprovação explícita do usuário antes da chamada real; não infira automaticamente a intenção de frases como "limpar" ou "resetar". --with_cancel_all também mata brackets TP/SL. Quando combinado com --preview, a resposta inclui uma nota de que o cancel-all seria executado primeiro, mas would_close[] ainda lista apenas as posições. |
position leverage <symbol> --leverage N [--margin_mode cross|isolated] | Define alavancagem. Padrão cross. |
position margin <symbol> --amount N --direction add|remove | A quantidade é o colateral da implantação (USDC ou USDG); válido apenas em posições isoladas. |
account mode --mode classic|unified | Alto risco. Altera o comportamento de margem em toda a conta. Inspecione query.py account info e obtenha aprovação explícita do usuário primeiro. |
account collateral --asset A --mode enabled|disabled | Alto risco. Altera se um ativo elegível contribui como colateral no modo Unified. Inspecione a conta e obtenha aprovação explícita do usuário primeiro. |
funds withdraw --asset A --amount N [--route perp|spot] | Rota padrão perp. Aceita qualquer símbolo de ativo da implantação ou ID numérico de ativo; collateral é um alias para o ativo de cotação quando não ambíguo. Isso cria uma solicitação de saque; os fundos podem entrar em um fluxo pendente/de reclamação e não aparecer na carteira instantaneamente. |
funds transfer --asset A --amount N --from_route perp|spot --to_route perp|spot | Move qualquer ativo da implantação entre seus buckets spot e perp. Sem assinatura L1, sem roteamento entre contas. |
order limit e order market retornam um client_order_index — salve-o; ele é o identificador para posterior order modify / order cancel.
Exemplo — mover colateral da implantação de perp para spot para financiar uma compra spot:
python3 scripts/trade.py funds transfer --asset collateral --amount 250 \
--from_route perp --to_route spot
Exemplo — habilitar colateral SPY na Robinhood Lighter:
python3 scripts/query.py account info
python3 scripts/trade.py account mode --mode unified
python3 scripts/query.py account info # aguarde até account_trading_mode ser 1
python3 scripts/trade.py account collateral --asset SPY --mode enabled
python3 scripts/query.py account info
Os dois comandos de escrita acima exigem aprovação explícita separada do usuário. account collateral --mode enabled rejeita ativos que a implantação selecionada não marca como elegíveis para colateral e rejeita contas em modo Classic.
Todo comando suporta --help. Veja references/schemas-write.md para o envelope de resposta, eco de precisão e tabela de códigos de erro.
Paper Trading (paper.py)
Simule negociações com snapshots reais do orderbook da Lighter sem credenciais, sem transmitir e sem risco. Todo o estado é local.
Os comandos do subconjunto compartilhado usam a mesma forma <grupo> <ação> que trade.py, então trocar o nome do script troca o mecanismo. Comandos exclusivos do paper trading permanecem simples.
Comandos
Exclusivos do paper trading (simples):
| Comando | Propósito |
|---|---|
init [--collateral N] [--tier T] | Cria conta de paper trading. Padrões: --collateral 10000 --tier premium. |
reset [--collateral N] [--tier T] | Limpa o estado. A forma sem argumentos reutiliza o colateral e o nível anteriores. |
set_tier --tier T | Altera o nível de taxa em uma conta existente (atualiza as configurações de mercado em cache). |
status [--no-refresh] | Resumo da conta: colateral, PnL, contagens de posições/negociações. Atualiza automaticamente os preços de marca para todas as posições abertas; passe --no-refresh para pular. |
positions [--symbol X] [--no-refresh] | Posições abertas. Sem --symbol lista todas. Atualiza automaticamente os preços de marca. |
trades [--symbol X] [--limit 50] | Histórico de negociações, mais recentes primeiro. |
health [--no-refresh] | Saúde da conta: TAV, requisitos de margem, alavancagem. Atualiza automaticamente os preços de marca. |
liquidation_price <symbol> [--no-refresh] | Preço de liquidação estimado para uma posição. Atualiza automaticamente os preços de marca. |
refresh <symbol> | Força a atualização do snapshot do orderbook de um mercado. Útil para pré-aquecer um mercado antes de negociar, ou quando você deseja dados de marca atuais sem passar --no-refresh em cada leitura. |
Subconjunto compartilhado (espelha a forma de trade.py):
| Comando | Propósito |
|---|---|
order market <symbol> --side buy|sell|long|short --amount N | Ordem market taker contra snapshot do livro ao vivo. |
order ioc <symbol> --side buy|sell|long|short --amount N --price N | Ordem IOC taker com preço limite. |
Regra de troca: troque trade.py ↔ paper.py para alternar entre negociação real e simulada. Todos os comandos compartilhados funcionam de forma idêntica em ambos.