Communitygithub.com

HeyElsa/elsa-openclaw

Ferramentas DeFi para análise de portfólio, busca de tokens e execução de swaps via API Elsa com micropagamentos x402.

O que é elsa-openclaw?

Esta skill oferece acesso à API DeFi Elsa para gerenciamento de portfólio, análise de tokens e execução de swaps, utilizando micropagamentos x402 para cobrança por chamada de API. Ela é ideal para desenvolvedores e agentes de IA que desejam interagir com finanças descentralizadas de forma programática, suportando redes como Base, Ethereum, Arbitrum, Optimism, Polygon, BSC, Avalanche e zkSync. A skill implementa um fluxo de swap seguro em 4 etapas (cotação, simulação, confirmação do usuário e execução) e oferece ferramentas de controle de orçamento para limitar gastos. Além de swaps, inclui ferramentas para consultar saldos, histórico de transações, posições em perpétuos e ordens limite, todas com custos de API pré-definidos.

Funciona com~Claude Code~Codex CLI~Cursor
npx skills add HeyElsa/elsa-openclaw

Perguntar na sua IA favorita

Abre um novo chat com esta habilidade de agente já pré-carregada.

Documentação

Ferramentas DeFi Elsa x402

Esta skill fornece acesso à API DeFi Elsa para gerenciamento de portfólio, análise de tokens e execução de swaps usando micropagamentos x402.

Procedimento Operacional Padrão

Controles de Orçamento

  • Máximo de $0,05 por chamada de API (configurável)
  • Máximo de $2,00 por dia (configurável)
  • Limite de 30 chamadas por minuto
  • O orçamento diário é redefinido à meia-noite no fuso horário configurado (padrão: UTC)

Fluxo de Swap Recomendado (OpenClaw)

Ao executar swaps, siga este fluxo de 4 etapas:

┌─────────────────────┐     ┌─────────────────────┐     ┌─────────────┐     ┌─────────────────────┐
│ 1. Obter Cotação    │ ──▶ │ 2. Simulação       │ ──▶ │ 3. Confirmar│ ──▶ │ 4. Executar Pipeline│
│ elsa_get_swap_quote │     │ elsa_execute_swap_ │     │ [Usuário    │     │ elsa_pipeline_run_ │
│                     │     │ dry_run            │     │  diz "sim"]  │     │ and_wait            │
└─────────────────────┘     └─────────────────────┘     └─────────────┘     └─────────────────────┘

Etapa 1: Obter Cotação - Mostrar ao usuário o que ele receberá

npx tsx scripts/index.ts elsa_get_swap_quote '{
  "from_chain": "base", "from_token": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
  "from_amount": "10", "to_chain": "base", "to_token": "0x4200000000000000000000000000000000000006",
  "wallet_address": "0x...", "slippage": 0.5
}'

Etapa 2: Simulação - Criar pipeline, obter pipeline_id

npx tsx scripts/index.ts elsa_execute_swap_dry_run '{...mesmos parâmetros...}'
# Retorna: { "pipeline_id": "abc-123", "confirmation_token": "..." }

Etapa 3: Confirmação do Usuário - Apresentar resultados e aguardar "sim" explícito

Etapa 4: Executar Pipeline - Assinar e transmitir transações

ELSA_ENABLE_EXECUTION_TOOLS=true npx tsx scripts/index.ts elsa_pipeline_run_and_wait '{
  "pipeline_id": "abc-123",
  "timeout_seconds": 180,
  "poll_interval_seconds": 3,
  "mode": "local_signer"
}'
# Automaticamente: assina tx approve → envia → assina tx swap → envia → retorna hashes das transações

Variáveis de Ambiente Necessárias

# Para pagamentos via API x402
PAYMENT_PRIVATE_KEY=0x...

# Para assinar transações de swap (opcional - usa PAYMENT_PRIVATE_KEY como fallback)
TRADE_PRIVATE_KEY=0x...

# Habilitar ferramentas de execução
ELSA_ENABLE_EXECUTION_TOOLS=true

Regras Críticas

  • NUNCA execute swaps sem mostrar a cotação ao usuário primeiro
  • NUNCA chame ferramentas de execução em um loop
  • NUNCA prossiga se os limites de orçamento forem excedidos
  • SEMPRE verifique elsa_budget_status se não tiver certeza sobre o orçamento restante
  • SEMPRE use o modo de simulação primeiro para qualquer operação de swap

Catálogo de Ferramentas

Ferramentas Somente Leitura (Sempre Disponíveis)

elsa_search_token

Busca tokens em blockchains suportadas.

npx tsx scripts/index.ts elsa_search_token '{"query": "USDC", "limit": 5}'

Entrada:

  • query (string, obrigatório): Nome, símbolo ou endereço do token
  • limit (number, opcional): Máximo de resultados (padrão: 10)

elsa_get_token_price

Obtém o preço atual de um token.

npx tsx scripts/index.ts elsa_get_token_price '{"token_address": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "chain": "base"}'

Entrada:

  • token_address (string, obrigatório): Endereço do contrato do token
  • chain (string, opcional): Nome da chain (padrão: "base")

elsa_get_balances

Obtém os saldos de tokens de uma carteira.

npx tsx scripts/index.ts elsa_get_balances '{"wallet_address": "0x..."}'

Entrada:

  • wallet_address (string, obrigatório): Endereço da carteira a ser consultada

elsa_get_portfolio

Obtém uma análise abrangente do portfólio.

npx tsx scripts/index.ts elsa_get_portfolio '{"wallet_address": "0x..."}'

Entrada:

  • wallet_address (string, obrigatório): Endereço da carteira a ser analisada

elsa_analyze_wallet

Obtém avaliação de comportamento e risco da carteira.

npx tsx scripts/index.ts elsa_analyze_wallet '{"wallet_address": "0x..."}'

Entrada:

  • wallet_address (string, obrigatório): Endereço da carteira a ser analisada

elsa_get_swap_quote

Obtém uma cotação de swap com roteamento otimizado.

npx tsx scripts/index.ts elsa_get_swap_quote '{
  "from_chain": "base",
  "from_token": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
  "from_amount": "100",
  "to_chain": "base",
  "to_token": "0x4200000000000000000000000000000000000006",
  "wallet_address": "0x...",
  "slippage": 0.5
}'

Entrada:

  • from_chain (string, obrigatório): Chain de origem
  • from_token (string, obrigatório): Endereço do token de origem
  • from_amount (string, obrigatório): Quantidade a ser trocada
  • to_chain (string, obrigatório): Chain de destino
  • to_token (string, obrigatório): Endereço do token de destino
  • wallet_address (string, obrigatório): Endereço da carteira
  • slippage (number, obrigatório): Tolerância de slippage (0-50)

elsa_execute_swap_dry_run

Simula um swap sem executar. Retorna um token de confirmação para execução posterior confirmada.

npx tsx scripts/index.ts elsa_execute_swap_dry_run '{
  "from_chain": "base",
  "from_token": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
  "from_amount": "100",
  "to_chain": "base",
  "to_token": "0x4200000000000000000000000000000000000006",
  "wallet_address": "0x...",
  "slippage": 0.5
}'

Saída inclui:

  • Resultados da simulação do swap
  • confirmation_token (se ELSA_REQUIRE_CONFIRMATION_TOKEN=true)
  • Token expira após ELSA_CONFIRMATION_TTL_SECONDS

elsa_budget_status

Verifica o uso atual do orçamento e os limites restantes.

npx tsx scripts/index.ts elsa_budget_status '{}'

Saída:

  • spent_today_usd: Valor gasto hoje
  • remaining_today_usd: Orçamento diário restante
  • calls_last_minute: Número de chamadas recentes
  • last_calls: Detalhes das chamadas recentes

elsa_get_limit_orders

Obtém todas as ordens limite de uma carteira.

npx tsx scripts/index.ts elsa_get_limit_orders '{"wallet_address": "0x...", "chain": "base"}'

Entrada:

  • wallet_address (string, obrigatório): Endereço da carteira a ser consultada
  • chain (string, opcional): Nome da chain (padrão: "base")

Saída:

  • orders: Array de ordens limite com status, preços e expiração

elsa_get_perp_positions

Obtém posições perpétuas de uma carteira.

npx tsx scripts/index.ts elsa_get_perp_positions '{"wallet_address": "0x..."}'

Entrada:

  • wallet_address (string, obrigatório): Endereço da carteira a ser consultada

Saída:

  • positions: Array de posições perpétuas abertas com PnL, alavancagem e preços de liquidação
  • total_unrealized_pnl: Soma dos lucros/prejuízos não realizados
  • total_margin: Margem total utilizada

elsa_get_transaction_history

Obtém o histórico de transações de uma carteira.

npx tsx scripts/index.ts elsa_get_transaction_history '{"wallet_address": "0x...", "chain": "base", "limit": 20}'

Entrada:

  • wallet_address (string, obrigatório): Endereço da carteira a ser consultada
  • chain (string, opcional): Filtrar por chain
  • limit (number, opcional): Máximo de resultados (padrão: 20, máximo: 100)

Saída:

  • transactions: Array de transações com detalhes, transferências de tokens e status

Ferramentas de Execução (Requerem ELSA_ENABLE_EXECUTION_TOOLS=true)

elsa_execute_swap_confirmed

Executa um swap confirmado. Requer simulação prévia e token de confirmação.

npx tsx scripts/index.ts elsa_execute_swap_confirmed '{
  "from_chain": "base",
  "from_token": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
  "from_amount": "100",
  "to_chain": "base",
  "to_token": "0x4200000000000000000000000000000000000006",
  "wallet_address": "0x...",
  "slippage": 0.5,
  "confirmation_token": "abc123..."
}'

elsa_pipeline_get_status

Verifica o status de um pipeline/transação.

npx tsx scripts/index.ts elsa_pipeline_get_status '{"pipeline_id": "pip_123456789"}'

elsa_pipeline_submit_tx_hash

Envia o hash de uma transação assinada para o pipeline.

npx tsx scripts/index.ts elsa_pipeline_submit_tx_hash '{"task_id": "task_123", "tx_hash": "0x..."}'

elsa_pipeline_run_and_wait

Orquestra a execução completa do pipeline com assinatura e envio automáticos.

npx tsx scripts/index.ts elsa_pipeline_run_and_wait '{
  "pipeline_id": "pip_123456789",
  "timeout_seconds": 120,
  "poll_interval_seconds": 2,
  "mode": "local_signer"
}'

Modos:

  • local_signer: Assina e transmite transações usando TRADE_PRIVATE_KEY
  • external_signer: Retorna tx_data não assinada para assinatura externa

elsa_create_limit_order

Cria uma ordem limite para executar quando o preço atingir o alvo.

ELSA_ENABLE_EXECUTION_TOOLS=true npx tsx scripts/index.ts elsa_create_limit_order '{
  "wallet_address": "0x...",
  "chain": "base",
  "from_token": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
  "to_token": "0x4200000000000000000000000000000000000006",
  "from_amount": "100",
  "limit_price": "0.0004",
  "expiry_hours": 24
}'

Entrada:

  • wallet_address (string, obrigatório): Endereço da carteira
  • chain (string, obrigatório): Nome da chain
  • from_token (string, obrigatório): Token a vender
  • to_token (string, obrigatório): Token a comprar
  • from_amount (string, obrigatório): Quantidade a vender
  • limit_price (string, obrigatório): Preço alvo para acionar a execução
  • expiry_hours (number, opcional): Horas até a ordem expirar (padrão: 24, máximo: 720)

elsa_cancel_limit_order

Cancela uma ordem limite existente.

ELSA_ENABLE_EXECUTION_TOOLS=true npx tsx scripts/index.ts elsa_cancel_limit_order '{
  "wallet_address": "0x...",
  "order_id": "order_123",
  "chain": "base"
}'

Entrada:

  • wallet_address (string, obrigatório): Endereço da carteira
  • order_id (string, obrigatório): ID da ordem a cancelar
  • chain (string, opcional): Nome da chain (padrão: "base")

elsa_open_perp_position

Abre uma posição em futuros perpétuos.

ELSA_ENABLE_EXECUTION_TOOLS=true npx tsx scripts/index.ts elsa_open_perp_position '{
  "wallet_address": "0x...",
  "market": "ETH-USD",
  "side": "long",
  "size_usd": "100",
  "leverage": 5,
  "take_profit": "4000",
  "stop_loss": "2800"
}'

Entrada:

  • wallet_address (string, obrigatório): Endereço da carteira
  • market (string, obrigatório): Par de mercado (ex.: "ETH-USD", "BTC-USD")
  • side (enum, obrigatório): "long" ou "short"
  • size_usd (string, obrigatório): Tamanho da posição em USD
  • leverage (number, opcional): Multiplicador de alavancagem (padrão: 1, máximo: 100)
  • take_profit (string, opcional): Preço de take profit
  • stop_loss (string, opcional): Preço de stop loss

elsa_close_perp_position

Fecha uma posição perpétua aberta.

ELSA_ENABLE_EXECUTION_TOOLS=true npx tsx scripts/index.ts elsa_close_perp_position '{
  "wallet_address": "0x...",
  "position_id": "pos_123",
  "close_percentage": 100
}'

Entrada:

  • wallet_address (string, obrigatório): Endereço da carteira
  • position_id (string, obrigatório): ID da posição a fechar
  • close_percentage (number, opcional): Porcentagem a fechar (padrão: 100, intervalo: 1-100)

Chains Suportadas

  • base (padrão)
  • ethereum
  • arbitrum
  • optimism
  • polygon
  • bsc
  • avalanche
  • zksync

Custos da API

FerramentaCusto Estimado
elsa_search_token$0,002
elsa_get_token_price$0,002
elsa_get_balances$0,002
elsa_get_portfolio$0,002
elsa_analyze_wallet$0,005
elsa_get_swap_quote$0,002
elsa_execute_swap_dry_run$0,005
elsa_get_limit_orders$0,002
elsa_get_perp_positions$0,002
elsa_get_transaction_history$0,002
elsa_create_limit_order$0,05
elsa_cancel_limit_order$0,01
elsa_open_perp_position$0,05
elsa_close_perp_position$0,05
elsa_execute_swap_confirmed$0,05

Em Breve

  • APIs Polymarket - Negociação e dados de mercados preditivos

Habilidades Relacionadas