A Agent Merchant API da Rozo remove essa suposição. Uma EOA de EVM pode se registrar como lojista com uma única assinatura de wallet; depois que o acesso é aprovado, uma segunda assinatura nova autoriza uma API key restrita a Orders para faturar e ler o status dos pagamentos. Os fundos são liquidados como USDC na Base no endereço que assinou, e o agente pode consultar a API até a liquidação chegar a payout_completed. Este guia percorre o ciclo completo.
O que o agente realmente recebe
- Uma conta de lojista vinculada à sua wallet: a primeira assinatura válida a cria e assinaturas repetidas reabrem a mesma conta — nunca há duplicata.
- Liquidação travada no servidor para USDC na Base no endereço que assinou. Nenhuma chamada de API pode redirecionar o destino do dinheiro.
- Uma API key restrita a Orders: no contrato atual, ela pode criar faturas e ler o status de pagamentos da própria conta. Não pode emitir credenciais Admin, gerenciar configurações da conta nem alterar a liquidação.
- Um link de pagamento para cada fatura, que o agente compartilha com o cliente. Para lojistas EVM nesta alpha, a liquidação é entregue como USDC na Base.
O ciclo de cinco passos
- Peça um challenge: GET /account-nonce?chain=evm&address=$ADDRESS&intent=merchant_onboard. O servidor devolve a mensagem exata a assinar; nonces anônimos são rejeitados.
- Assine localmente e registre-se: POST /account-onboard com endereço, assinatura e nonce. A chave privada nunca sai do ambiente do agente.
- Solicite acesso e emita uma credencial restrita: chame POST /account-credentials/request com a sessão de wallet e reenvie o mesmo pedido no máximo algumas vezes por dia para verificar o status. Depois de aprovado, assine um challenge novo de credential_issue e chame POST /account-credentials com scope "orders". A credencial emitida tem escopo Orders; credenciais Orders não podem criar chaves Admin.
- Crie uma fatura: POST /payment-api com um orderId estável, um Idempotency-Key, informações de exibição e o valor em USDC. Não envie destination. Após uma falha de rede, tente de novo com o mesmo orderId e a mesma chave de idempotência.
- Consulte o status do pagamento: faça polling com a key Orders e o orderId estável até payout_completed. Trate o estado retornado como autoritativo mesmo se a entrega de webhook ou e-mail falhar. Se a resposta incluir o hash da transação de payout, você pode verificá-lo adicionalmente na Base.
O contrato completo legível por máquina está em https://partners.rozo.ai/llms.txt — foi escrito para ser colado diretamente em um agente.
Por que as permissões são deliberadamente estreitas
Entregar uma credencial de pagamento a um agente autônomo é exatamente o lugar para ser paranoico. A API foi desenhada para que o raio de dano de uma key vazada seja pequeno:
- Keys restritas a Orders não podem cunhar outras keys nem mudar a liquidação, e suas leituras ficam restritas à própria conta. Listar e revogar credenciais emitidas por wallet exige uma assinatura nova e vinculada ao propósito.
- Emitir credenciais exige uma assinatura de wallet nova — um token de sessão roubado, sozinho, não cunha uma key.
- Todo challenge é de uso único, com propósito fixo e prazo de expiração definido pelo servidor.
- O endereço de recebimento é o endereço que assinou, imposto pelo servidor. Uma key Orders vazada não muda o endereço de liquidação configurado, mas pode criar faturas indesejadas e expor o status de pagamentos — revogue-a imediatamente com uma prova de wallet nova.
Como obter acesso (alpha)
O programa de credenciais é por convite durante a alpha. Após o registro, o agente chama POST /account-credentials/request e reenvia o mesmo pedido no máximo algumas vezes por dia para verificar o status. A aprovação é uma decisão humana do lado da Rozo, mas nenhum e-mail ou mensagem direta é necessário. O ciclo de credenciais e faturamento atualmente suporta EOAs de EVM com liquidação em USDC na Base. EOAs de Solana e Stellar podem se registrar e liquidar USDC na cadeia do próprio endereço que assinou, mas ficam fora deste ciclo de credenciais.
Wallets de contrato EVM não são suportadas nesta alpha, e contas somente-wallet não têm caminho de recuperação: se a chave que assina for perdida, a Rozo não consegue recuperar o lojista nem transferir a propriedade manualmente.
Comece em https://partners.rozo.ai/agent.