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_statusse 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 tokenlimit(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 tokenchain(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 origemfrom_token(string, obrigatório): Endereço do token de origemfrom_amount(string, obrigatório): Quantidade a ser trocadato_chain(string, obrigatório): Chain de destinoto_token(string, obrigatório): Endereço do token de destinowallet_address(string, obrigatório): Endereço da carteiraslippage(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 hojeremaining_today_usd: Orçamento diário restantecalls_last_minute: Número de chamadas recenteslast_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 consultadachain(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çãototal_unrealized_pnl: Soma dos lucros/prejuízos não realizadostotal_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 consultadachain(string, opcional): Filtrar por chainlimit(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_KEYexternal_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 carteirachain(string, obrigatório): Nome da chainfrom_token(string, obrigatório): Token a venderto_token(string, obrigatório): Token a comprarfrom_amount(string, obrigatório): Quantidade a venderlimit_price(string, obrigatório): Preço alvo para acionar a execuçãoexpiry_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 carteiraorder_id(string, obrigatório): ID da ordem a cancelarchain(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 carteiramarket(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 USDleverage(number, opcional): Multiplicador de alavancagem (padrão: 1, máximo: 100)take_profit(string, opcional): Preço de take profitstop_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 carteiraposition_id(string, obrigatório): ID da posição a fecharclose_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
| Ferramenta | Custo 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