Skip to main content
X402 é um protocolo de pagamento em cadeia baseado em HTTP 402 Payment Required. Com a capacidade X402 da Ace Data Cloud, o chamador pode realizar pagamentos em cadeia diretamente com USDC em cada solicitação de API, sem a necessidade de criar um Token de API ou pré-carregar o saldo da conta. Este conjunto de documentos está organizado na ordem de integração real: primeiro, execute uma solicitação mínima, depois integre o SDK, e em seguida, compreenda a rede, planos de cobrança, pagamento de pedidos e Facilitator. Recomenda-se ler a tabela abaixo de cima para baixo.

​
Caminho de Integração Recomendado

Se você deseja apenas chamar a API da Ace Data Cloud, use prioritariamente o SDK oficial:
  • TypeScript: @acedatacloud/sdk + @acedatacloud/x402-client
  • Python: acedatacloud + acedatacloud-x402
Endereços de código-fonte e pacotes públicos: O SDK irá automaticamente realizar a primeira solicitação sem autenticação, analisar o 402 Payment Required, chamar o manipulador de pagamento e tentar novamente esses passos com o PAYMENT-SIGNATURE. Você só precisa preparar uma carteira com USDC e escolher a rede que deseja usar. Se você deseja que sua API também suporte recebimentos X402, precisará ler a documentação do Facilitator para entender a relação entre paymentRequirements, paymentPayload, /verify e /settle.

​
Status de Suporte

O X402 da Ace Data Cloud foi validado em API pública, SDK oficial, Facilitator e caminhos de liquidação em cadeia. A tabela abaixo resume o estado atual com base nas dimensões de capacidade mais comumente usadas pelos desenvolvedores durante a integração. A saída a seguir é apenas para ilustrar a forma de retorno do caminho validado. Durante a integração real, sempre siga o accepts retornado pela API atual.
Nota:
  • Os pacotes npm e PyPI foram instalados e importados com sucesso em um ambiente limpo.
  • A solicitação de API não paga retorna 402, accepts inclui os métodos de pagamento disponíveis para Base, SKALE e Solana.
  • accepts[].network é a identificação CAIP-2, que deve ser correspondida como uma string CAIP-2 ao selecionar a rede no cliente.
  • Tanto o SDK TypeScript quanto o SDK Python podem lidar automaticamente com 402 e completar a tentativa de pagamento.
  • Base exact, SKALE exact, Base upto e pagamento de pedidos têm endereços de explorer que podem ser abertos publicamente.
  • O limite de assinatura para Base upto é de 95215 atomic USDC, o liquidação real é de 3 atomic USDC, refletindo a característica de liquidação baseada em medição posterior de acordo com o uso real.
  • Solana exact validou HTTP 402 -> HTTP 200 e a saída do modelo. Devido a possíveis limitações de consulta RPC pública, recomenda-se usar RPC Solana próprio ou registros de liquidação do lado da plataforma para confirmar a assinatura da transação.

​
Considerações para 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 no documento:
  • accepts[].maxAmountRequired é o valor máximo que pode ser assinado na solicitação atual.
  • accepts[].asset é o contrato ou mint USDC a ser utilizado nesta solicitação.
  • accepts[].extra.chainId, accepts[].extra.facilitatorAddress e accepts[].extra.verifyingContract participarão da assinatura de dados tipados EVM.
  • upto requer que a carteira autorize o USDC da cadeia alvo com Permit2; se não autorizado, retornará PERMIT2_ALLOWANCE_REQUIRED.
  • Se houver uma clara intenção de usar medição posterior, passe preferScheme: 'upto' no SDK TypeScript; caso contrário, o SDK escolherá o primeiro requisito disponível retornado pelo servidor na rede.

​
Escopo de verificação pública

Antes da integração, é possível verificar esses pontos de entrada públicos e o comportamento do SDK:
  • Solicitações de API sem Authorization ou PAYMENT-SIGNATURE retornarão 402 Payment Required, e o accepts na resposta é a única base de assinatura para esta solicitação.
  • Tanto o SDK TypeScript quanto o SDK Python fornecem um manipulador de pagamento; a camada de transporte do SDK chamará o manipulador e tentará novamente ao receber 402.
  • https://facilitator.acedata.cloud/.well-known/x402: retorna as redes, esquemas e pontos de extremidade suportados pelo Facilitator; o preço da API ainda é baseado no 402 retornado em tempo real pela solicitação alvo.
  • https://facilitator.acedata.cloud/supported: retorna as redes e esquemas suportados pelo Facilitator.
  • O repositório X402Client contém ferramentas avançadas de verificação on-chain, que podem ser usadas para confirmar assinaturas, tentativas e comportamentos de liquidação; a saída da ferramenta não substitui o accepts retornado pela API online.
upto pertence à liquidação de medição posterior, adequada para APIs onde o uso real só é conhecido após a resposta, como preenchimento de chat e chamadas de modelo. Atualmente, apenas a Base oferece upto; se a verificação da assinatura falhar, verifique se o chain id, endereço do facilitador, spender, contrato USDC e a permissão Permit2 estão consistentes com a resposta 402.