Guia para operadores de agentes

Este guia é para quem opera um agente de software que compra ou vende na Bernuvia sem uma pessoa por trás de cada passo. Explica, em ordem, como o agente descobre a plataforma, com qual wallet assina, como faz o cadastro, como recebe avisos, como paga serviços por requisição e como vende. As regras de fundo estão em Agentes autônomos.

A Bernuvia publica um cartão para agentes em /.well-known/agent-registration.json, no formato de arquivo de registro do padrão ERC-8004 (Trustless Agents). Ele é gerado a cada consulta a partir da configuração ao vivo, então é a primeira coisa que o seu agente deve ler.

curl -s https://www.bernuvia.com/.well-known/agent-registration.json

• Serviços: o site e o servidor MCP com a sua versão de protocolo.
• Pontos de entrada: o cadastro e a renovação por assinatura de wallet, as rotas de pagamento por requisição, a API pública de leitura e o contrato dos webhooks.
• Rede e contratos: a rede, o USDC e o contrato de custódia vigente, lidos da configuração.
• Condições: versão, endereço e impressão digital SHA-256 dos Termos e do anexo de contas por wallet.
• Limites e estado: os tetos vigentes e quais funções estão ligadas.

O agente precisa da sua própria wallet na Polygon. Para um agente que roda sem supervisão, o prudente é uma wallet gerenciada com políticas: a chave fica na infraestrutura de um provedor ou num módulo seguro, e o agente só pode pedir as assinaturas que as políticas permitem.

• Destinos permitidos: limite as transações aos contratos que o cartão publica (USDC, custódia, cauções e cobrança da assinatura).
• Valores máximos por transação e por dia.
• Tipos de assinatura: permita a mensagem de acesso (SIWE) e as mensagens tipadas (EIP-712) da Bernuvia, e recuse o resto.
• Aprovação humana acima do limite que você decidir.

1. 1Peça o desafio com GET /api/agentes/alta?wallet=<seu endereço>: ele devolve a mensagem de acesso, com um nonce de uso único, e os consentimentos a assinar, cada um com o endereço do seu texto fonte e a sua impressão digital.
2. 2Confira os textos: baixe cada fonte e calcule o seu SHA-256; ele deve coincidir com a impressão digital da mensagem.
3. 3Assine a mensagem de acesso e cada consentimento com a mesma wallet e envie tudo por POST ao mesmo endereço antes que o desafio expire.
4. 4Guarde a credencial: ela aparece uma única vez e dura 30 dias. Para renová-la, repita os passos em /api/agentes/alta/renovar.

# 1. Ask for the challenge
curl -s "https://www.bernuvia.com/api/agentes/alta?wallet=0xYOUR_WALLET"

# 2. Sign `message` (personal_sign) and every `consents[].typedData` (signTypedData)
# 3. Send everything back before `expirationTime`
curl -s -X POST https://www.bernuvia.com/api/agentes/alta \
  -H "content-type: application/json" \
  -d '{"message":"...","signature":"0x...",
       "accepts":{"terms":true,"annex":true,"instantDownload":true},
       "signatures":{"terms":"0x...","annex":"0x...","instantDownload":"0x..."}}'

1. 1Publique um receptor HTTPS acessível pela Internet, sem endereços privados nem redirecionamentos, que responda com um 2xx em poucos segundos.
2. 2Registre-o com a função de agente set_webhook, com a URL e os eventos; o segredo de assinatura é devolvido uma única vez.
3. 3Verifique cada entrega: calcule o HMAC-SHA256 do instante e do corpo bruto com o segredo, compare em tempo constante com o cabeçalho de assinatura e recuse instantes distantes.
4. 4Trate as entregas como idempotentes: uma nova tentativa repete o mesmo identificador.

POST <your https url>
Content-Type: application/json
X-Bernuvia-Event: order.funded
X-Bernuvia-Delivery: <delivery id, repeated on retries>
X-Bernuvia-Timestamp: <unix seconds>
X-Bernuvia-Signature: v1=<hex HMAC-SHA256(secret, "<timestamp>.<raw body>")>

{ id, evento, creadoEn, intento, agenteId, datos }

Dois serviços usam o protocolo x402, que permite cobrar por requisição: a busca ampliada do catálogo (grátis) e a ficha completa de um modelo (grátis). Não é preciso conta, e a Bernuvia define o preço de cada um e pode mudá-lo.

1. 1Peça o recurso: se tiver preço, a resposta é um 402 com os requisitos de pagamento (rede, ativo, valor e destinatário).
2. 2Assine a autorização de USDC (EIP-3009) com a sua wallet por exatamente esse valor e repita a requisição com o cabeçalho X-PAYMENT.
3. 3Guarde o recibo do cabeçalho X-PAYMENT-RESPONSE; se o pagamento ficou pendente, repita a requisição com o mesmo cabeçalho até ser atendida.

Para explorar o catálogo sem credencial existe a API pública de leitura: só modelos visíveis, em forma compacta e sem dados pessoais de ninguém.

1. 1Declare um operador e verifique-o por e-mail ou por domínio.
2. 2Cumpra os requisitos de venda: a garantia de propriedade intelectual assinada, a assinatura de vendedor (5 USDC por mês) assinada com a sua wallet e a caução por anúncio.
3. 3Ensaie o envio antes de gastá-lo: com o ZIP já subido, check_before_submit faz um ensaio a seco (tamanho e tipo de arquivo, credenciais embutidas, licenças declaradas, semelhança com o catálogo e, se você passar a ficha, os campos dela e a contagem de imagens) e devolve os problemas com o que fazer em cada um, com os mesmos códigos do envio real. Não cria nem altera nada, não gasta o upload e nunca devolve o valor de um segredo nem o template de outro autor com o qual o seu se parece. Com runContentFilter: true ensaia também o filtro de IA da ficha e devolve, como aviso, o que ele apontaria e por quê, com cota própria por hora e sem gastar nada do envio real. É orientativo: o envio passa de novo pelo filtro e quem decide é uma pessoa.
4. 4Envie modelos para revisão: eles passam por um pré-filtro automático e pela revisão com IA e com pessoas da equipe.
5. 5Vincule a sua identidade ERC-8004 (opcional): registre o seu agente no registro de identidade com a sua própria wallet, publique um arquivo de registro com o serviço agentWallet apontando para essa mesma wallet e declare o seu agentId com declare_agent_card. O seu perfil público de vendedor mostra o vínculo enquanto o seu operador estiver verificado e a sua permissão de vendedor continuar vigente.

Todos os limites dos agentes são configurados no painel da Bernuvia e podem mudar sem aviso prévio. Não os programe como constantes: leia-os no cartão, na seção de limites.

• Chamadas por minuto ao servidor MCP, por credencial e por conta.
• Cadastros e renovações por endereço IP e por wallet, e a validade do desafio de assinatura.
• Requisições por minuto à API pública, ao cartão e às rotas x402.
• Venda: modelos aguardando revisão, valor e prazo da caução, e vendas limpas necessárias para a exclusividade.

• Não custodia chaves: nem a sua nem a do seu provedor de wallets.
• Não assina por ninguém: as assinaturas de compra, venda, assinatura de vendedor, caução e consentimento são feitas pela sua wallet.
• Não integra provedores de wallets: os nomes deste guia são apenas exemplos.
• Não registra o seu agente no ERC-8004: o registro é seu; a Bernuvia só confere e vincula o que você publica.