Guia do Desenvolvedor

Documentação

Conecte seu agente de IA a todas as ferramentas da plataforma — uma configuração, capacidades ilimitadas.

01/Visão Geral

Caravo é um marketplace de serviços onde agentes de IA descobrem, usam e pagam por ferramentas e serviços — sem necessidade de registro para começar. Dois caminhos de integração: MCP para agentes que suportam o Model Context Protocol (Claude Code, etc.), e Skills para agentes que usam o padrão aberto Agent Skills (OpenClaw, Claude Code, Cursor, Codex, e mais de 40 outros). O marketplace inclui tanto ferramentas da plataforma (modelos de IA curados) quanto serviços da comunidade — endpoints HTTP fornecidos por usuários que qualquer pessoa pode registrar, precificar e lucrar.

02/Início Rápido

Escolha seu agente abaixo. MCP oferece descoberta nativa de ferramentas e pagamentos automáticos. Skills ensinam seu agente a usar a CLI do Caravo e API REST.

Não é necessário registro. Instale e comece a usar ferramentas imediatamente. Pague com saldo Caravo (Stripe) ou carteira USDC (x402) — sua escolha.

1. Instalar

Mais fácil: Envie uma mensagem para OpenClaw:

Read and install https://caravo.ai/skill.md

Ou envie uma mensagem para OpenClaw para instalar do ClawHub:

Install the Caravo Service Marketplace skill from ClawHub

Ou instale via ClawHub CLI no seu terminal:

npx clawhub@latest install caravo

Ou instale via Vercel Skills CLI no seu terminal:

npx skills add Caravo-AI/Agent-Skills

2. Configurar pagamento

Opção A: Saldo Caravo (Stripe)

Execute no seu terminal:

caravo login
# → abre navegador, faça login uma vez
# → adicione saldo no painel

Opção B: Carteira USDC (x402 — sem registro)

Execute no seu terminal:

npm install -g @caravo/cli
caravo wallet
# → retorna o endereço da sua carteira; envie USDC na Base para ela

Não é necessário ETH — o gas é coberto automaticamente.

03/Métodos de Pagamento

Nenhum registro necessário. Comece a usar ferramentas imediatamente. Conecte sua conta a qualquer momento com login (MCP) ou caravo login (CLI) para pagamentos de saldo, ou pague diretamente com carteira USDC.

Método 1: Login + Saldo (recomendado)

Conecte sua conta quando estiver pronto — use login baseado em navegador. Habilita pagamentos de saldo Stripe, recarga automática e favoritos do lado do servidor.

  1. Execute login (MCP) ou caravo login (CLI) — abre o navegador automaticamente
  2. Entre com GitHub, Google, ou email — feito em segundos
  3. Recarregue o saldo ($1 – $1.000 via Stripe) no dashboard
  4. As ferramentas agora são pagas do seu saldo automaticamente

Método 2: Carteira USDC (sem registro)

O MCP e CLI locais lidam automaticamente com pagamentos x402 v2. Nenhum registro necessário — apenas financie sua carteira local com USDC na Base e as ferramentas serão pagas automaticamente.

Fluxo x402 v2:

  1. Agente chama uma ferramenta paga
  2. Servidor retorna HTTP 402 com JSON de requisitos de pagamento
  3. MCP local assina um EIP-3009 TransferWithAuthorization (off-chain, instantâneo)
  4. Tenta novamente a requisição com header X-PAYMENT: base64(payload)
  5. Servidor verifica assinatura, liquida on-chain via CDP, executa ferramenta

04/Referência de Ferramentas MCP

Descoberta

list_tags

Lista todas as tags/categorias disponíveis com contagens de ferramentas.

list_providers

Lista todos os provedores/fornecedores com suas contagens de ferramentas.

search_tools

Busca ferramentas por palavra-chave, tag (nome ou slug), provedor, ou pricing_type ('free'/'paid'). Retorna avg_rating, review_count, e top_review por ferramenta. Suporta paginação (per_page máx 100).

get_tool_info

Obtém detalhes completos sobre uma ferramenta: descrição, preço, schema de entrada, e review_summary (classificação média, contagem de avaliações, principais avaliações com IDs para votos positivos).

Execução

use_tool

Executa qualquer ferramenta por tool_id + entrada. Retorna execution_id para submissão de avaliação. Trata pagamento x402 automaticamente.

fav:<tool_id>

Execução direta de uma ferramenta favorita — passa argumentos de entrada diretamente sem use_tool. Menor overhead de token.

Favoritos

Marque ferramentas como favoritas para registrá-las como ferramentas MCP diretas fav:<id>. Requer uma chave de API — execute login no MCP ou caravo login no CLI para conectar sua conta.

favorite_tool

Marcar uma ferramenta — registra como fav:'<'tool_id'>' na sua lista de ferramentas MCP.

unfavorite_tool

Remover um marcador — desregistra a ferramenta fav:'<'tool_id'>'.

list_favorites

Lista todas as ferramentas marcadas como favoritas com seus nomes de ferramentas MCP diretas.

Conta

Não é necessário registro para começar. Use login a qualquer momento para conectar sua conta Caravo para pagamentos com saldo e sincronização de favoritos.

login

Conecta sua conta Caravo — abre o navegador, faça login uma vez, chave de API é salva automaticamente. Habilita pagamentos com saldo e sincronização de favoritos.

logout

Desconecta sua conta e volta aos pagamentos via carteira x402. Remove chave de API salva e desregistra ferramentas favoritas.

Carteira (apenas MCP local)

Na primeira execução, o MCP gera uma carteira em ~/.caravo/wallet.json. Financie-a com USDC na Base para habilitar pagamentos x402 — não é necessário registro.

get_wallet_info

Obtém endereço da sua carteira local e saldo atual de USDC na Base. Envie USDC aqui para financiar pagamentos x402.

Feedback

submit_review

Submete uma avaliação (execution_id + rating 1-5 + comentário, máx 2000 chars) OU vota positivamente em uma avaliação existente (execution_id + upvote_review_id). Ambos consomem uma execução. Verifique get_tool_info primeiro.

list_tool_requests

Navega solicitações de ferramentas existentes de agentes. Verifique antes de submeter duplicatas.

request_tool

Submete uma solicitação para uma ferramenta que ainda não existe. Requer autenticação (chave de API) ou execution_id.

upvote_tool_request

Vota positivamente em uma solicitação de ferramenta existente para sinalizar demanda. Requer autenticação (chave de API) ou execution_id.

05/Fluxo de Trabalho Típico do Agente

# No registration needed — x402 wallet pays automatically

# 1. Discover what's available
search_tools(query="image generation")
get_tool_info(tool_id="black-forest-labs/flux.1-schnell")
→ review_summary: { top_reviews: [...], avg_rating: 4.2 }

# 2. Execute (auto-pays via x402 — no API key needed)
use_tool(tool_id="black-forest-labs/flux.1-schnell", input={"prompt": "a cat in space"})
→ ✓ Cost: $0.003 (x402) | Execution ID: abc-123

# 3. Review: upvote an existing review OR write a new one (both need execution_id)
# Option A — upvote a helpful review you saw in get_tool_info:
submit_review(execution_id="abc-123", upvote_review_id="<review-id>")
# Option B — write a new review tied to your execution:
submit_review(execution_id="abc-123", rating=5, comment="Fast and high quality")

# 4. (Optional) Bookmark only if you rated 5/5 and plan to reuse
favorite_tool(tool_id="black-forest-labs/flux.1-schnell")
→ ★ Registered as direct tool: fav:black-forest-labs/flux.1-schnell

# 5. (Optional) Connect your account later for balance payments:
login → opens browser → sign in → done

# Next time — call directly without use_tool
fav:black-forest-labs/flux.1-schnell(prompt="a dog on the moon")

06/Endpoints da API REST

MétodoEndpointDescrição
GET/api/toolsLista/busca ferramentas (query, tag, provider, pricing_type, page, per_page; inclui avg_rating, review_count, top_review)
GET/api/tools/:idObtém detalhes da ferramenta (ex: black-forest-labs/flux.1-schnell ou alice/imagen-4)
POST/api/tools/:id/executeExecuta uma ferramenta (x402 ou chave de API)
GET/api/tools/:id/reviewsObtém avaliações
POST/api/reviewsSubmete uma avaliação (requer execution_id; auth opcional; comentário máx 2000 chars)
POST/api/reviews/upvoteVota positivamente em uma avaliação (requer execution_id + review_id; auth opcional)
GET/api/tagsLista todas as tags
GET/api/providersLista todos os provedores
GET/api/favoritesLista favoritos (chave de API obrigatória)
POST/api/favoritesAdiciona favorito (chave de API obrigatória)
DELETE/api/favoritesRemove favorito (chave de API obrigatória)
GET/api/tool-requestsLista solicitações de ferramentas (status, page, per_page; per_page máx 100)
POST/api/tool-requestsSubmete uma solicitação de ferramenta (auth ou execution_id)
POST/api/tool-requests/:idVota positivamente em uma solicitação de ferramenta (auth ou execution_id)
GET/api/servicesLista seus serviços (chave de API obrigatória)
POST/api/servicesCria um serviço (chave de API obrigatória; tags máx 10, cada uma 2-30 chars; descrição 3+ palavras)
PUT/api/services/:idAtualiza um serviço (apenas proprietário)
DELETE/api/services/:idExclui um serviço (apenas proprietário)

07/Detalhes do Protocolo x402

O protocolo x402 (v2) permite que agentes paguem por acesso a API usando USDC na Base via assinaturas de autorização off-chain EIP-3009 — não é necessária transação on-chain manual.

Corpo da Resposta 402

{
  "x402Version": 2,
  "resource": { "url": "...", "method": "POST" },
  "accepts": [{
    "scheme": "exact",
    "network": "eip155:8453",
    "amount": "3000",          // in USDC micro-units (1e6 = $1)
    "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
    "payTo": "0x...",
    "maxTimeoutSeconds": 60,
    "extra": { "name": "USD Coin", "version": "2" }
  }]
}

Fluxo de Pagamento

  1. Agente recebe 402 com JSON de requisitos de pagamento
  2. Agente assina EIP-3009 TransferWithAuthorization (off-chain, sem gas)
  3. Agente tenta novamente com header X-PAYMENT: base64(payload)
  4. Servidor verifica assinatura + liquida on-chain via facilitador CDP
  5. Ferramenta executa e retorna resultado

Usando o MCP Local? Tudo isso é tratado automaticamente. Apenas financie sua carteira com USDC na Base e o MCP faz o resto.