Saltar para o conteúdo principal
Este tutorial usa uma solicitação mínima de API para explicar o fluxo completo do Ace Data Cloud X402. O objetivo não é primeiro escrever código complexo, mas entender primeiro: por que a primeira solicitação retorna 402, o que há em accepts e como PAYMENT-SIGNATURE transforma a mesma solicitação de API em uma solicitação paga.

Preparação

Você precisa preparar: Não é necessário API Token ao chamar a API Ace Data Cloud com X402. A primeira solicitação do SDK não inclui Authorization, o Gateway retorna 402 Payment Required e os requisitos de pagamento; o SDK tenta novamente automaticamente após assinar.

Instalar o SDK

Código-fonte e endereços dos pacotes: TypeScript:
Python:
Se for usar Solana, também será necessário instalar as dependências correspondentes:
A dependência do signer Solana para a versão Python já está incluída em acedatacloud-x402. A saída da verificação de instalação e importação em um ambiente temporário limpo:
Explicação dos resultados:
  • Os pacotes npm e PyPI são ambos pacotes realmente publicados, não nomes de placeholder na documentação.
  • acedatacloud-x402[cli] instala a CLI, e o subcomando approve-permit2 pode ser usado para autorização Permit2 em cenários upto.

A primeira solicitação retornará 402

Você pode primeiro usar curl para ver o que uma solicitação não paga retorna. O exemplo abaixo não gerará cobrança, porque não inclui PAYMENT-SIGNATURE:
O corpo da resposta incluirá o array accepts, com uma estrutura comum como a seguinte:
O mesmo conteúdo do desafio também será colocado no cabeçalho de resposta PAYMENT-REQUIRED em formato base64, facilitando ao cliente ler os requisitos de pagamento sem analisar o body. O resumo da saída do programa para uma solicitação não paga da API de produção é o seguinte:
Explicação dos resultados:
  • A primeira solicitação não inclui Authorization ou PAYMENT-SIGNATURE, portanto retorna HTTP 402 e não gera cobrança.
  • accepts é a única base confiável de assinatura para esta solicitação, incluindo redes opcionais, scheme, limite de valor, endereço de recebimento e endereço do ativo.
  • network é um identificador CAIP-2, e o cliente deve corresponder pela string CAIP-2 ao selecionar a rede.
  • O limite de valor para esta solicitação mínima de chat gpt-4o-mini é 95215 USDC atomic, ou seja, 0.095215 USDC.
  • Cada solicitação deve ler a resposta 402 daquela vez; não codifique rigidamente o valor de exemplo no código de negócio.
Significado dos campos:

Concluir a nova tentativa de pagamento com o SDK

Abaixo está o exemplo mínimo em TypeScript. Ele especifica network: 'base', e o handler selecionará o payment requirement do Base na resposta 402 desta vez; o valor real e o endereço de recebimento ainda estão sujeitos a accepts:
Por trás deste código, ocorrem quatro etapas:
  1. O SDK envia uma solicitação de API comum, sem Authorization.
  2. O Gateway retorna 402 Payment Required e accepts.
  3. createX402PaymentHandler seleciona o payment requirement de network = 'base' e assina PAYMENT-SIGNATURE.
  4. O SDK tenta novamente com o mesmo corpo da solicitação, e o Gateway chama o Facilitator para verificar e liquidar antes de permitir a passagem para a API de destino.

Ver as capacidades suportadas pelo Facilitator

A API X402 não depende de um diretório de recursos. O cliente chama diretamente uma API conhecida e usa o 402 Payment Required e o accepts retornados em tempo real por essa solicitação como a única base para preço e assinatura. A declaração de capacidades do Facilitator está em:
Ela descreve apenas /supported, /verify, /settle e as redes de pagamento atualmente habilitadas, sem listar recursos de API. O endereço do Facilitator de produção da Ace Data Cloud é:
É possível verificar quais redes e schemes ele suporta:
Os kinds retornados listarão as redes e os schemes suportados pelo Facilitator. Durante a chamada real, ainda deve-se usar o accepts retornado pela API como referência. Saída de /supported do Facilitator:
O resultado indica:
  • /supported indica que o Facilitator possui capacidades de verificação e liquidação para essas redes e schemes.
  • Tanto Base quanto Solana suportam exact; upto está atualmente disponível apenas na Base.
  • Se uma API específica permite determinada rede ainda depende do accepts 402 dessa API.