API, MCP e CLI

Tudo o que o Swap e o Payments fazem dá para usar sem navegador. A API monta as transações e as confere, e a assinatura fica sempre com você.

O guia completo, sempre atual, é swap.vurto.cc/agent-api.md (em inglês). Leia ao vivo: quando esta página e o guia discordarem, valem o guia e a API no ar.

Endereços base

O /v1 é público, aberto a qualquer origem e estável dentro do v1: mudança que quebra vira v2.

Regras da API

• Sem custódia. A API devolve calldata, dados tipados ou uma transação Solana sem assinatura. Ela nunca pede chave privada nem frase de recuperação, e recusa o pedido que parece ter uma com 400 secret_in_payload.
• wallet não é autenticação. Ele diz qual carteira vai assinar. A assinatura, ou uma credencial emitida para aquela carteira, é a prova.
• Uma leitura pede credencial: a lista do histórico de trocas, GET /executions. O resto funciona sem.
• Valores: mande amount como texto decimal humano; todo valor numa resposta é um inteiro em texto, na menor unidade do token. Leia como inteiro grande, nunca como número de ponto flutuante.
• Erros vêm como {"error": {"code", "message", "details"}}. Decida pelo code; o message pode ser mostrado a uma pessoa.

Credenciais

Opcionais, e valem a pena quando você atende muita gente a partir de um endereço só: elas trocam o teto por IP pelo orçamento da própria credencial. Para emitir uma, abra swap.vurto.cc, conecte a carteira EVM dona dela, entre assinando e clique no ícone de chave no cartão daquela carteira, no painel de carteiras. O segredo aparece uma vez só. Mande assim:

Authorization: Bearer vswap_<id>_<segredo>

A credencial tem escopos (read, build) e um orçamento de 240 unidades de custo a cada 60 segundos corridos.

Limites por IP

Um 429 quer dizer espere, não repita num laço.

O que tem nela

Uma primeira chamada

curl -sS https://swap.vurto.cc/v1/quote \
  -H 'content-type: application/json' \
  --data '{"chainId": 42161, "tokenIn": "USDC", "tokenOut": "WETH",
           "amount": "100", "slippageBps": 50, "wallet": "<o endereço EVM que vai assinar>"}'

Sem wallet as cotações são indicativas: rotas e preços reais, mas que não dá para montar depois.

A Solana muda em quatro pontos

1. O chainId é o texto "solana-mainnet".
2. Não existe aprovação, então a montagem é uma transação e nunca uma lista steps[].
3. A assinatura usa uma chave Solana.
4. Assinatura não é recibo. Confirme com GET /v1/svm/tx antes de dizer que deu certo. Endereços são base58 e diferenciam maiúscula de minúscula: nunca mude a caixa deles.

MCP para agentes de IA

Cole https://swap.vurto.cc/mcp num cliente MCP. As ferramentas correspondem uma a uma à API: swap_quote, swap_build, swap_status, report_execution, prepare_signing, double_quote, double_build, nn_quote, nn_build, destination_challenge, destination_authorize, invoice_create, invoice_get, invoice_pay, invoice_report_payment, invoice_analysis_pay, invoice_report_analysis_payment, payout_batch, payout_charge, payout_reuse, payout_report_payment e wallet_check.

Uma skill pronta de agente para o Payments: swap.vurto.cc/skills/vurto-payments/SKILL.md. Para Lend e Swap por um agente, o AnA tem o próprio MCP em https://ana.vurto.cc/mcp, com o guia do agente.

CLI

Servida pelo próprio site com checksum, não por um registro de pacotes:

curl -sO https://swap.vurto.cc/cli/vurto-swap-0.3.6.tgz
curl -s https://swap.vurto.cc/cli/vurto-swap-0.3.6.tgz.sha256 | sha256sum -c -
npm i -g ./vurto-swap-0.3.6.tgz

Alguns comandos:

vurto-swap check   --wallet 0xQUEM_RECEBE --chain base
vurto-swap quote   --chain arbitrum --in USDC --out WETH --amount 100 --wallet 0xSeuEndereco
vurto-swap swap    --chain arbitrum --in USDC --out WETH --amount 100 --wallet 0xSeuEndereco --json > plan.json
vurto-swap sign    --wallet 0xSeuEndereco < plan.json
vurto-swap invoice create --chain base --to 0xQUEM_RECEBE --token USDC --amount 100 --memo "aluguel"
vurto-swap payout  --file folha.csv --chain base --token USDC --wallet 0xQUEM_PAGA --batch

A CLI assina na sua máquina, com a sua carteira ou num prompt do terminal sem eco.

Contrato de lote chamado direto

No EVM, o lote montado pelo Vurto é autorizado pelo Vurto e paga 0,1%. O mesmo contrato de lote também pode ser chamado por qualquer um sem essa autorização: aí ele não faz checagem nenhuma e cobra 1% na própria rede.