Saltar para o conteúdo principal
X402 é um protocolo de pagamento on-chain baseado em HTTP 402 Payment Required. Com os recursos X402 do Ace Data Cloud, os chamadores não precisam criar um API Token nem pré-carregar o saldo da conta, podendo em vez disso concluir diretamente pagamentos on-chain com USDC em cada solicitação de API. Este conjunto de documentos está organizado na ordem real de integração: primeiro execute uma solicitação mínima, depois integre o SDK e, em seguida, compreenda redes, planos de cobrança, pagamento de pedidos e o Facilitator. Recomenda-se ler de cima para baixo de acordo com a tabela abaixo.

Caminho de integração recomendado

Se você deseja apenas chamar a API do Ace Data Cloud, priorize o uso dos SDKs oficiais:
  • TypeScript: @acedatacloud/sdk + @acedatacloud/x402-client
  • Python: acedatacloud + acedatacloud-x402
Código-fonte público e endereços dos pacotes: O SDK concluirá automaticamente as etapas de primeira solicitação sem autenticação, análise de 402 Payment Required, chamada do payment handler e nova tentativa com PAYMENT-SIGNATURE. Você só precisa preparar uma carteira com USDC e escolher a rede que deseja usar. Se você deseja que sua própria API também ofereça suporte ao recebimento de pagamentos com X402, será necessário ler a documentação do Facilitator para compreender a relação entre paymentRequirements, paymentPayload, /verify e /settle.

Status de suporte

O Ace Data Cloud X402 já foi validado na API pública, nos SDKs oficiais, no Facilitator e no fluxo de liquidação on-chain. A tabela abaixo resume o status atual por dimensão de capacidade mais comumente usada por desenvolvedores durante a integração. A saída abaixo é usada apenas para ilustrar o formato de retorno dos caminhos validados. Durante a integração real, use sempre como referência o accepts retornado pela API atual.
Explicação:
  • Os pacotes npm e PyPI foram instalados e importados com sucesso em ambientes limpos.
  • Solicitações de API não pagas retornam 402, e accepts inclui os métodos de pagamento disponíveis para Base e Solana.
  • accepts[].network é um identificador CAIP-2; os clientes devem corresponder usando a string CAIP-2 ao selecionar uma rede.
  • Tanto o SDK TypeScript quanto o SDK Python conseguem processar automaticamente o 402 e concluir a nova tentativa paga.
  • Base exact, Base upto e pagamentos de pedidos têm endereços de explorer que podem ser abertos publicamente.
  • O limite assinado do Base upto é 95215 USDC atômicos, e o settlement real é de 3 USDC atômicos, refletindo a característica de liquidação pós-medição com base no uso real.
  • O Solana exact verificou HTTP 402 -> HTTP 200 e a saída do modelo. Como consultas públicas de RPC podem sofrer limitação de taxa, para reconciliação rigorosa é recomendável usar seu próprio RPC Solana ou confirmar a assinatura da transação por meio dos registros de liquidação da plataforma.

Observações de integração

Ao integrar, os desenvolvedores devem priorizar os requisitos de pagamento em tempo real retornados pela solicitação atual, em vez de copiar os valores ou endereços de exemplo da documentação:
  • accepts[].maxAmountRequired é o valor máximo que pode ser assinado para a solicitação atual.
  • accepts[].asset é o contrato ou mint de USDC a ser usado nesta solicitação.
  • accepts[].extra.chainId, accepts[].extra.facilitatorAddress e accepts[].extra.verifyingContract participam da assinatura EVM typed data.
  • upto requer que a carteira autorize primeiro o Permit2 para USDC na cadeia de destino; quando não autorizado, será retornado PERMIT2_ALLOWANCE_REQUIRED.
  • Se desejar explicitamente usar medição pós-paga, passe preferScheme: 'upto' no SDK TypeScript; caso contrário, o SDK escolherá o primeiro requirement disponível retornado pelo servidor nessa rede.

Escopo que pode ser verificado publicamente

Antes da integração, você pode verificar estes pontos de entrada públicos e comportamentos dos SDKs:
  • Solicitações de API sem Authorization ou PAYMENT-SIGNATURE retornarão 402 Payment Required; o accepts na resposta é a única base de assinatura para a solicitação atual.
  • Tanto o SDK TypeScript quanto o SDK Python fornecem payment handler; a camada de transporte do SDK chamará o handler ao receber 402 e tentará novamente uma vez.
  • https://facilitator.acedata.cloud/.well-known/x402: retorna as redes, schemes e endpoints de protocolo suportados pelo Facilitator; os preços da API ainda se baseiam no 402 retornado em tempo real pela solicitação de destino.
  • https://facilitator.acedata.cloud/supported: retorna as redes e schemes suportados pelo Facilitator.
  • O repositório X402Client contém ferramentas avançadas de verificação on-chain, que podem ser usadas para confirmar o comportamento de assinatura, nova tentativa e settlement; a saída das ferramentas não substitui o accepts retornado pela API online.
upto é uma liquidação de medição pós-paga, adequada para APIs cujo uso real só é conhecido após a resposta, como complementação de chat e chamadas de modelo. Atualmente, apenas a Base fornece upto; se a verificação da assinatura falhar, verifique se o chain id, endereço do facilitator, spender, contrato USDC e Permit2 allowance correspondem à resposta 402.