Skip to main content
Um agente com uma chave de API pode gastar tudo o que a chave pode gastar. Isso funciona quando uma pessoa está de olho e é desconfortável quando ninguém está. As correções usuais moram fora do agente, em um dashboard ou em um alerta de cobrança que te avisa do problema depois que ele aconteceu. A Venice suporta um segundo caminho de entrada. Em vez de uma chave, o agente tem uma carteira. Ele autentica assinando uma mensagem, paga por cada requisição a partir de um saldo em USDC vinculado a esse endereço de carteira, e cada cobrança cai em um livro-razão que ele pode consultar. Não há conta, não há dashboard e não há chave para vazar. O teto é o saldo, e você decide o que colocar lá. Este guia constrói um agente que faz exatamente isso, sob um orçamento que ele mesmo impõe.

Rode este notebook no Google Colab

Todo passo abaixo como um notebook executável. Ele roda sem uma carteira com saldo e para no muro do pagamento, para que você veja o fluxo inteiro antes de gastar qualquer coisa.

Como Funciona

Quatro peças em movimento, três das quais são apenas HTTP: A inferência em si é a chamada comum a /chat/completions. A única diferença é qual header você envia.

Quanto Custa Para Começar

Dois números importam e eles não são o mesmo número. O top-up mínimo é cinco dólares. Esse é o menor valor que /x402/top-up liquida, e ele é retornado na resposta de descoberta em vez de ficar codificado em lugar nenhum, então leia isso em vez de confiar nesta página. O saldo mínimo para fazer uma chamada é dez centavos. Uma carteira que segure menos que isso recebe um 402 da inferência mesmo tendo dinheiro. Então cinco dólares é a menor carteira que vale a pena financiar, e cinco dólares é o que este guia dá ao agente. Vale saber o que isso compra: uma pergunta curta ao qwen3-5-9b custa cerca de vinte e sete tokens de entrada e vinte e seis de saída, o que nos preços daquele modelo dá aproximadamente sete milionésimos de dólar. Cinco dólares está na ordem de três quartos de milhão de perguntas. O orçamento aqui não é uma restrição apertada, é um raio de explosão.

Configurando

O SDK do x402 faz a assinatura do pagamento. Não faça isso na mão: a autorização de transferência é dados tipados EIP-712 e um nonce reutilizado falha na verificação de formas tediosas de depurar.
O SDK Python do x402 exige Python 3.10 ou superior. O Colab está bem. Um Python de sistema que veio com o macOS pode não estar.
Crie agent.py com a configuração. BUDGET_USD é o teto que o agente impõe a si mesmo, definido aqui como a carteira inteira. Diminua-o e o agente para antes do dinheiro acabar, que é o único botão que você provavelmente vai mexer.

Uma Carteira que o Agente Possui

O agente precisa de um par de chaves. Em produção, essa é uma carteira que você financiou deliberadamente e cuja chave vive num gerenciador de segredos. Enquanto você está construindo, gerar uma descartável é a jogada certa, porque uma carteira sem dinheiro não consegue fazer nada caro por acidente.
Mantenha a chave privada fora do notebook. No Colab, coloque-a em Secrets e leia com userdata.get("WALLET_KEY").

Fazendo Login em Vez de Autenticar

Não há chave para enviar, então cada requisição carrega uma prova de que o dono da carteira a fez. A prova é uma mensagem EIP-4361, assinada, e depois codificada em base64 no header SIGN-IN-WITH-X. O formato da mensagem é exato. A Venice reconstrói esses bytes do lado dela e verifica sua assinatura contra eles, então uma linha em branco solta significa uma assinatura rejeitada em vez de um erro útil.
Três regras governam esses headers, e todas as três existem para impedir replay. A assinatura vale por cinco minutos a partir de Issued At. Cada nonce é de uso único por cerca de cinco minutos e meio. E o assinante precisa bater com a carteira no path, então uma carteira não pode inspecionar outra e recebe um 403 por tentar. A consequência prática é que você assina um header novo por requisição em vez de guardar um em cache. Assinar é local e gratuito, então isso não custa nada.
Numa carteira nova:
canConsume é o campo em que ramificar. Ele leva em conta o piso de dez centavos, então você não precisa.

Colocando Dinheiro

Fazer o top-up são duas requisições. A primeira pergunta o que a Venice aceita e não é autenticada, porque ainda não há nada para autenticar. A segunda carrega uma autorização de transferência assinada.
A descoberta retorna uma entrada por trilho. Base e Solana hoje:
Dois detalhes ali são fáceis de passar batido. amount está em unidades base, e o USDC tem seis casas decimais, então 5000000 são cinco dólares e não cinco milhões de nada. No trilho Solana, extra.feePayer é uma conta operada pela Venice que cobre a taxa da transação, o que é o que permite uma carteira pagar sem manter SOL.
O controle de gasto padrão é a primeira coisa que vai te parar. O SDK vem com max_amount_per_payment definido em um dólar, e o top-up mínimo da Venice é cinco, então um cliente sem modificação rejeita todo trilho ofertado e levanta NoMatchingRequirementsError antes mesmo de contatar a rede. Aumente o teto deliberadamente em vez de desligar os controles de gasto.
Liquidar de uma carteira sem USDC retorna um 400 com PAYMENT_VERIFICATION_FAILED. Esse é o formato esperado de falha: a assinatura estava correta e a transferência não.

Pagando Por Chamada

Com um saldo em mãos, a inferência é uma requisição normal que por acaso carrega uma assinatura. Desligar o system prompt da Venice importa mais do que parece: ele vale cerca de mil e setecentos tokens de entrada por chamada, que é duas ordens de magnitude a mais do que a pergunta em si.
Tratar 402 como um resultado normal em vez de uma exceção é todo o design. Um agente que paga o próprio caminho vai ficar sem dinheiro em algum momento, e ficar sem dinheiro não é um crash.

Lendo o Que Ele Gastou

O livro-razão é a fonte da verdade. Em vez de estimar por contagens de token, pergunte o que foi de fato cobrado.
Cada linha remete de volta à chamada que a causou:
Linhas de TOP_UP e REFUND também aparecem aqui, com valores positivos. Filtrar por CHARGE te dá o gasto.

A Execução com Orçamento

Agora o loop. Antes de cada chamada, o agente verifica o quanto gastou, e se recusa a começar trabalho que não pode pagar.
Rode com os cinco dólares completos e o orçamento nunca segura, que é o resultado honesto nesses preços. Para ver o teto de fato funcionando, defina um que uma única chamada vai romper:

Onde Isso Te Deixa

O agente segura seu próprio dinheiro, prova sua identidade com uma assinatura, e não pode exceder um limite que você definiu, tudo sem que uma conta exista em lugar nenhum. Para um job agendado, uma função serverless, ou qualquer coisa a que você preferiria não entregar uma chave de vida longa, essa é uma postura de segurança materialmente diferente. Algumas coisas que valem a pena fazer em seguida:

Limite no protocolo

Os controles de gasto no SDK são por pagamento, não por sessão. Combine-os com o loop de orçamento acima, para que um bug em um não derrote o outro.

Recarregar quando esvaziar

Capture o 402, faça top-up e tente de novo. É isso que o venice-x402-client faz para você no lado TypeScript.

Pagar na Solana

Mesmo fluxo, trilho diferente. Assine Ed25519 e configure o feePayer retornado, para que a carteira não precise de SOL.

Dê a ele trabalho de verdade

Troque a lista de tarefas por um loop de tool calling e o livro-razão começa a te mostrar quanto cada decisão custou.
Para a referência completa dos endpoints, veja x402 top-up e Usando x402 com a API Venice.