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.
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.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 headerSIGN-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.
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.
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.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.
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.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.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.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.