Tutorial x402: deixe seu agente de IA recarregar o AIHubMix com USDC

O AIHubMix agora aceita recargas em USDC. Seu agente de IA pode adicionar crédito à própria conta com o USDC da carteira: sem abrir página web e sem que ninguém precise clicar em um botão.

Com o x402, uma recarga pode ser de apenas US$ 1. O agente recarrega conforme usa, então você não precisa depositar um saldo grande com antecedência.

São dois passos: preparar um token, uma carteira e algum USDC na web e em um app, depois executar nosso script pronto de recarga com um único comando. Cerca de 20 segundos após o pagamento, o crédito aparece na sua conta.

Se ajudar, você pode acompanhar com este vídeo de 30 segundos:

O jeito mais fácil: se você usa uma ferramenta de IA que consegue executar comandos no terminal, como Claude Code, Cursor ou Codex, conclua o passo 1 e depois envie o link deste post com a frase "configure isso para mim". Ela seguirá as "Instruções para assistentes de IA" no final deste post. Você preenche o token e a chave privada sozinho, uma única vez, sem enviá-los para a IA.

Antes de começar

• Os valores devem ser dólares inteiros, de US$ 1 a US$ 10 por recarga por padrão
• Cada conta pode criar até 3 pedidos por dia (UTC)
• Só há suporte para USDC na Base mainnet, e não há testnet, então comece com US$ 1
• Este canal foi feito para programas; uma pessoa não consegue pagar pelo navegador. Para recargas manuais, continue usando Alipay ou Stripe

Passo 1: obter um token, uma carteira e USDC

Tudo nesta etapa acontece na web ou em um app de celular.

1. Obtenha seu token de acesso ao sistema

Faça login em aihubmix.com, abra suas configurações pessoais e gere um token de acesso ao sistema (uma string de 32 caracteres).

Atenção: este não é a chave de API que começa com sk-. Os dois não são intercambiáveis.

2. Crie uma carteira para pagamentos

No MetaMask ou em um app de carteira semelhante, crie uma conta nova apenas para os pagamentos do agente. Não use sua carteira principal. Depois:

• Copie o endereço da conta (ele começa com 0x); você enviará USDC para ele no próximo passo
• Exporte a chave privada nos detalhes da conta e guarde-a em um gerenciador de senhas. Quem tiver a chave privada pode movimentar o dinheiro da carteira

3. Compre USDC e envie para esta carteira

O MetaMask é uma carteira: você guarda a chave privada, e o script precisa dela para assinar. A Coinbase é uma exchange, onde você compra criptomoedas. Fundos em uma conta de exchange não vêm com uma chave privada, então o script não consegue usá-los. Por isso você compra na exchange primeiro e depois envia o USDC para a carteira da etapa anterior.

Usando a exchange Coinbase como exemplo (não a Coinbase Wallet):

1. Compre USDC na Coinbase
2. Envie o USDC para o endereço que você copiou e escolha a rede Base
3. Envie um pouco mais do que pretende recarregar, por exemplo 1,5 a 2 USDC para uma recarga de US$ 1

Aguarde um pouco e depois abra https://basescan.org/address/your-wallet-address. Quando aparecer um saldo de USDC, significa que ele chegou. Outras exchanges que suportam saques de USDC na Base também funcionam; veja a documentação da Base para mais opções.

A carteira não precisa de nenhum ETH: a FluxA paga a taxa de rede do pagamento.

Passo 2: executar o script de recarga

Não há nada para baixar nem arquivo para criar: o uv baixa o script da web e o executa. Abra o Terminal (PowerShell no Windows) e copie e cole os comandos abaixo.

1. Instale o uv (uma vez)

O uv é uma ferramenta Python que prepara tudo o que o script precisa para rodar.

macOS / Linux:

curl -LsSf https://astral.sh/uv/install.sh | sh

Windows (PowerShell):

powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

Quando terminar, feche o terminal e abra-o novamente.

2. Verifique sua configuração (não gasta nada)

uv run https://raw.githubusercontent.com/zch456/public_resource/main/aihubmix-x402-topup/topup.py check

Na primeira execução, o script pede seu token de acesso ao sistema (System access token) e a chave privada da carteira (Wallet private key). O que você digitar não aparece na tela; cole e pressione Enter. Depois ele pergunta se deve salvar (Save to ...? [Y/n]). Pressione Enter para salvar e você não precisará digitá-los de novo. A primeira execução demora um pouco enquanto o uv prepara o ambiente.

Quando aparecer isto, sua configuração está pronta:

Wallet: 0x... (USDC balance 2.0)
Access token and private key are fine. Ready to top up.

3. Recarregue

uv run https://raw.githubusercontent.com/zch456/public_resource/main/aihubmix-x402-topup/topup.py 1

O 1 no final é o valor em dólares. Se tudo correr bem, você verá:

Wallet: 0x... (USDC balance 2.0)
tradeNo: pl_XXXXXXXX
txHash: 0x...
result: credited

result: credited significa que o crédito chegou. Faça login em aihubmix.com e você verá seu saldo aumentar; US$ 1 adiciona 500.000 de cota.

Se a última linha mostrar outra coisa:

• failed: o pedido foi fechado ou expirou. Execute novamente se precisar; isso usa mais um dos pedidos de hoje.
• pending: o crédito não foi confirmado em 10 minutos. Não é uma falha, e o crédito chegará depois, automaticamente. Não execute de novo.

Solução de problemas

Se aparecer um timeout ou erro de rede depois que o tradeNo for impresso, o dinheiro pode já ter sido pago. Não execute de novo imediatamente. Verifique seu saldo após alguns minutos; se nada tiver chegado, entre em contato conosco com o tradeNo.

O token e a chave privada são salvos em ~/.aihubmix-topup.env no seu computador (na pasta do seu usuário, no Windows). No macOS e no Linux, somente a sua conta consegue ler esse arquivo. Para alterar o token ou a chave privada, edite este arquivo.

Integrando ao seu agente

• Depois que a configuração estiver salva, seu agente pode recarregar executando uv run https://raw.githubusercontent.com/zch456/public_resource/main/aihubmix-x402-topup/topup.py 1 sempre que precisar de crédito, sem ninguém por perto
• São permitidos apenas 3 pedidos por dia, então limite a frequência de recargas do agente e nunca repita a criação de pedidos em loop
• Salve o tradeNo e o txHash da saída em um banco de dados ou log para conciliação
• Para uso de longo prazo, baixe o script e fixe uma versão antes de executá-lo; você pode ler o código-fonte antes
• Se US$ 10 por recarga ou 3 por dia não forem suficientes, entre em contato conosco para aumentar os limites

Instruções para assistentes de IA

Se você é um assistente de IA ajudando um usuário a configurar recargas em USDC no AIHubMix, siga estes passos na ordem:

1. Confirme que o usuário concluiu o passo 1: ele tem um token de acesso ao sistema, além de uma carteira com USDC na Base mainnet e a chave privada dela. Se não tiver, guie-o pelo passo 1 primeiro.
2. Execute uv --version para verificar se o uv está instalado. Se não estiver, instale-o com os comandos do passo 2.
3. Execute uv run https://raw.githubusercontent.com/zch456/public_resource/main/aihubmix-x402-topup/topup.py check.
4. Se ele informar que o token ou a chave privada está faltando (Missing access token or private key), o script criou o arquivo de configuração ~/.aihubmix-topup.env. Peça ao usuário que o abra em um editor de texto e o preencha sozinho (no macOS, execute open -e ~/.aihubmix-topup.env; no Windows, execute notepad $HOME\.aihubmix-topup.env). Não leia este arquivo, não coloque o token nem a chave privada em nenhum comando e não peça que o usuário os envie para você.
5. Quando o usuário tiver preenchido o arquivo, execute check novamente até ver Access token and private key are fine. Ready to top up.. Se houver erro, trate-o com a tabela de Solução de problemas acima.
6. Uma recarga gasta dinheiro real. Confirme o valor com o usuário antes de executar uv run https://raw.githubusercontent.com/zch456/public_resource/main/aihubmix-x402-topup/topup.py <amount>.

Por dentro: o que o script faz

O script faz cinco coisas, em ordem:

1. Verifica o saldo: criar um pedido consome um dos pedidos de hoje, então primeiro ele confirma que a chave privada é válida e que há USDC suficiente.
2. Cria um pedido: ele chama POST /api/pay/fluxa/crt e recebe um link de pagamento e um número de pedido, tradeNo. O token vai no cabeçalho Authorization exatamente como está, sem Bearer. Erros de negócio também retornam como HTTP 200, então ele verifica o campo success na resposta.
3. Verifica a solicitação de pagamento: um GET no link de pagamento retorna HTTP 402 com os requisitos de pagamento. Antes de assinar, ele verifica quatro itens: scheme é exact, network é eip155:8453, asset é o contrato do USDC na Base mainnet, e maxAmountRequired é igual ao valor × 1.000.000. Se algum deles não bater, ele para.
4. Assina e paga: ele assina uma autorização de transferência de USDC com a chave privada, coloca-a no cabeçalho X-PAYMENT e envia o GET para o link de pagamento novamente. Um 200 ou 202 significa que o pagamento foi enviado; o txHash na resposta é o comprovante on-chain desse pagamento. Nenhuma das requisições leva o token do AIHubMix.
5. Aguarda o crédito: ele chama GET /api/pay/fluxa/qry?trade_no=... a cada 8 segundos até que o status vire TRADE_SUCCESS. O servidor só atualiza a cada 5 segundos, então consultar mais rápido não ajuda.

Cada link de pagamento também é válido por 30 minutos e pode ser pago apenas uma vez.

Implementando em outra linguagem

A resposta 402 do link de pagamento tem esta aparência:

{
  "x402Version": 1,
  "accepts": [{
    "scheme": "exact",
    "network": "eip155:8453",
    "maxAmountRequired": "1000000",
    "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
    "payTo": "0x....",
    "maxTimeoutSeconds": 600,
    "extra": {"name": "USD Coin", "version": "2"}
  }]
}

A assinatura usa o formato EIP-712, sobre a estrutura TransferWithAuthorization da EIP-3009:

Domínio de assinatura: name = USD Coin, version = 2 (use os valores de extra na resposta 402, se presentes), chainId = 8453, verifyingContract = 0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913.

O valor do cabeçalho X-PAYMENT é a codificação base64 deste JSON:

{
  "x402Version": 1,
  "scheme": "exact",
  "network": "eip155:8453",
  "payload": {
    "signature": "0x...",
    "authorization": {
      "from": "0x...", "to": "0x...", "value": "1000000",
      "validAfter": "...", "validBefore": "...", "nonce": "0x..."
    }
  }
}

Fontes

• Documentação do x402
• EIP-3009: Transfer With Authorization
• EIP-712: Typed structured data hashing and signing
• Circle: endereços de contrato do USDC
• Guia de instalação do uv