Agente Pagador de IA x402

💸 Agente de IA que Paga com x402

Um agente de IA com a sua própria carteira de criptomoedas que paga pelos dados de que precisa: sem chaves de API, sem subscrições, sem registo.

Faça uma pergunta em linguagem natural. O Claude decide qual a API paga que responde à pergunta e chama uma ferramenta de fetch. A API responde 402 Payment Required com uma cotação de preço; o agente paga automaticamente em USDC através do padrão aberto x402 (agora sob a alçada da Linux Foundation) e responde com base nos dados que acabou de comprar.

Tudo neste tutorial é gratuito e autossuficiente. Você executa a própria API paga (seller.py, ~60 linhas), os pagamentos são liquidados em USDC de testnet na Base Sepolia através do facilitador público do x402.org e a carteira do comprador é financiada através de uma faucet gratuita. Você é simultaneamente o comprador e o vendedor, pelo que acompanha o ciclo de pagamento completo sem qualquer dinheiro real envolvido. Exatamente o mesmo código do agente funciona em mainnet contra qualquer API x402 em produção.

Funcionalidades

• Utilização de ferramentas orientada pelo agente: o Claude escolhe o endpoint pago adequado à pergunta e apresenta os dados devolvidos
• Pagamento 402 automático: o SDK x402 assina um pagamento em USDC quando a API devolve um desafio; os endpoints de demonstração custam entre $0.001 e $0.002 em USDC de testnet
• Limite rígido de orçamento: um teto de preço por chamada (MAX_PRICE_USDC, por omissão $0.05), para que um agente mal configurado nunca gaste mais do que o definido
• Modo sem LLM: --direct <URL> paga e obtém qualquer URL x402 apenas com uma carteira, para que possa ver o fluxo de pagamento de forma isolada
• O seu próprio vendedor: seller.py é uma API pay-per-call completa em ~60 linhas de FastAPI; redefina os preços, adicione endpoints ou aponte o agente para qualquer outro vendedor x402

Como Começar?

1. Clone o repositório do GitHub

git clone https://github.com/Shubhamsaboo/awesome-llm-apps.git
cd awesome-llm-apps/starter_ai_agents/ai_x402_paying_agent

2. Instala as dependências necessárias:

npm install

pip install -r requirements.txt

3. Crie duas carteiras descartáveis (comprador e vendedor)

Qualquer carteira EVM funciona (MetaMask, ou python -c "from eth_account import Account; a=Account.create(); print(a.address, a.key.hex())"). Vai precisar de:

• uma carteira de comprador a partir da qual o agente gasta: exporte a respetiva chave privada
• um endereço de vendedor que recebe os pagamentos: qualquer segundo endereço que controle (apenas recebe; não precisa de fundos nem de chave no servidor)

export X402_PRIVATE_KEY='0x...'   # buyer wallet private key
export SELLER_ADDRESS='0x...'     # seller receive address

⚠️ Para isto, utilize carteiras descartáveis dedicadas (nunca a sua carteira principal).

4. Financie o comprador com USDC de testnet gratuito

Aceda a faucet.circle.com, selecione Base Sepolia e cole o endereço do comprador. Recebe USDC de teste instantaneamente; não é necessário nenhum token de gas em lado nenhum (os pagamentos x402 são sem gas para ambas as partes).

5. Inicie a sua API paga (terminal 1)

uvicorn seller:app --port 4021

Experimente sem pagar e veja o desafio 402: curl -i http://localhost:4021/api/fortune

6. Defina a sua chave de API da Anthropic (ignore no modo --direct)

export ANTHROPIC_API_KEY='your-api-key-here'

7. Execute o agente (terminal 2)

# Full agent: natural-language question → paid data → answer
python x402_paying_agent.py "Roll me a d20 and read me my fortune"

# Payment flow only, no LLM needed:
python x402_paying_agent.py --direct "http://localhost:4021/api/fortune"

Como funciona

you ──question──▶ Claude ──tool call──▶ GET your local paid API
                                          │ 402 Payment Required ($0.001)
                                          ▼
                                   x402 SDK signs USDC payment
                                          │ retry with payment header
                                          ▼
                              facilitator verifies + settles on Base Sepolia
                                          │
                                     200 OK + data ──▶ Claude answers

Toda a negociação de pagamento se resume a 3 pedidos HTTP e liquida-se on-chain em segundos, e, como você executa o vendedor, pode observar ambos os lados do processo.

Para além da demo

• Aponte-o para a economia real: substitua o URL por qualquer API ativa compatível com x402 numa rede mainnet; o código do agente é idêntico. Diretórios de endpoints x402 ativos estão disponíveis em x402.org.
• Passar para produção: carteiras geridas: esta demo mantém a carteira como uma chave privada em bruto para que possa ver todas as peças em movimento. Para um agente em produção, o CDP x402 SDK da Coinbase encapsula o mesmo padrão aberto com carteiras geridas (sem chave privada para guardar), controlos de despesa do lado do cliente (limites por pagamento, limites diários renováveis, listas de beneficiários autorizados) e liquidação alojada. A salvaguarda MAX_PRICE_USDC deste tutorial é uma versão mínima da mesma ideia: limitar o que um gastador autónomo pode gastar antes de o fazer.