Fazer um pagamento x402

Use o Pay para executar uma API x402 V2 e dar ao Claude Code um cliente HTTP com suporte a pagamentos. A API, a carteira do pagador e a liquidação usam o sandbox da Solana, por isso este tutorial não requer uma conta nem fundos reais.

Precisa de um terminal, do Pay e do Claude Code instalados.

1. Instalar o Pay

No macOS, instale o binário pré-compilado:

brew install pay
pay --version

Noutras plataformas, instale o pacote npm:

npm install --global @solana/pay
pay --version

2. Iniciar uma API sandbox x402

Crie o ficheiro x402-demo.yaml:

name: x402-demo
subdomain: x402-demo
title: "x402 Demo"
description: "Minimal x402 V2 sandbox endpoint."
category: devtools
version: v1
routing:
  type: respond
operator:
  currencies:
    usd: ["USDC"]
  network: "localnet"
  fee_payer: true
endpoints:
  - method: GET
    path: "report"
    description: "Return a sandbox report."
    metering:
      schemes: [x402-exact]
      dimensions:
        - direction: usage
          unit: requests
          scale: 1
          tiers:
            - price_usd: 0.001

Inicie a API e deixe-a em execução:

pay --sandbox server start x402-demo.yaml --bind 127.0.0.1:1402

O esquema x402-exact faz deste um endpoint exclusivo para x402. O modo sandbox cria e financia automaticamente contas temporárias de operador e de pagador.

3. Iniciar o agente com o Pay

Noutro terminal, inicie o Claude Code no modo sandbox:

pay --sandbox claude

O Pay anexa as suas ferramentas MCP locais à sessão do agente. O agente não recebe uma chave privada.

4. Fazer um pedido x402

Cole este prompt no agente:

Use Pay to make exactly one sandbox x402 API request to
http://127.0.0.1:1402/report.

Before paying, show me the amount and ask for approval. Then return the API
result and payment receipt. Do not make any other paid requests.

O pedido segue um ciclo completo de pagamento x402 V2:

1. A API devolve 402 Payment Required com um desafio PAYMENT-REQUIRED.
2. O Pay valida os requisitos x402 e apresenta as condições do pagamento.
3. Após a aprovação, a carteira sandbox assina e o Pay repete o pedido com PAYMENT-SIGNATURE.
4. A API devolve o resultado com um recibo PAYMENT-RESPONSE.

Nenhum fundo real é movimentado. Rejeitar a aprovação interrompe o pedido.

Continue com x402 na Solana para criar um cliente e um servidor de recursos x402 V2, ou torne-se um facilitador x402.