> ## Documentation Index > Fetch the complete documentation index at: https://docs.acedata.cloud/llms.txt > Use this file to discover all available pages before exploring further. # X402 Guia de Integração > Platform API guide - Ace Data Cloud 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. | Tutorial | Cenário Aplicável | Link | | - | - | - | | Introdução Rápida | Primeiro, entenda o processo 402, `accepts` e `PAYMENT-SIGNATURE` com uma solicitação mínima | [Introdução Rápida ao X402](https://platform.acedata.cloud/documents/x402-quickstart) | | SDK TypeScript | Chamar a API da Ace Data Cloud em navegadores, Node.js ou aplicativos front-end | [Integração do SDK TypeScript](https://platform.acedata.cloud/documents/x402-typescript-sdk) | | SDK Python | Chamar a API em serviços Python, scripts, Agents ou pipelines de dados | [Integração do SDK Python](https://platform.acedata.cloud/documents/x402-python-sdk) | | Pagamento de Pedidos | Pagar pedidos do console da Ace Data Cloud com X402 | [Tutorial de Pagamento de Pedidos](https://platform.acedata.cloud/documents/x402-order-payment) | | Redes e Métodos de Pagamento | Compreender ativos, assinaturas e cenários aplicáveis de Base, SKALE e Solana | [Redes e Métodos de Pagamento](https://platform.acedata.cloud/documents/x402-networks) | | `exact` e `upto` | Diferenciar API de preço fixo e API de liquidação pós-consumo | [Descrição do Plano de Cobrança](https://platform.acedata.cloud/documents/x402-metered-upto) | | Descrição de Preços | Compreender a relação entre os preços do X402 e o preço unitário de Créditos, e os preços reais de cada serviço | [Descrição de Preços do X402](https://platform.acedata.cloud/documents/x402-pricing) | | Facilitator | Compreender a relação entre `verify`, `settle` e a API de recebimento autônoma | [Integração do Facilitator](https://platform.acedata.cloud/documents/x402-facilitator) | | E2E e Solução de Problemas | Verificar entradas públicas, executar ferramentas de validação avançadas, localizar problemas comuns de 402, assinatura e liquidação | [Validação E2E e Solução de Problemas](https://platform.acedata.cloud/documents/x402-e2e-troubleshooting) | ## 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: | Projeto | Endereço | | - | - | | SDK Ace Data Cloud | [https://github.com/AceDataCloud/SDK](https://github.com/AceDataCloud/SDK) | | Cliente X402 | [https://github.com/AceDataCloud/X402Client](https://github.com/AceDataCloud/X402Client) | | Facilitator X402 | [https://github.com/AceDataCloud/FacilitatorX402](https://github.com/AceDataCloud/FacilitatorX402) | | npm SDK | [https://www.npmjs.com/package/@acedatacloud/sdk](https://www.npmjs.com/package/@acedatacloud/sdk) | | npm Cliente X402 | [https://www.npmjs.com/package/@acedatacloud/x402-client](https://www.npmjs.com/package/@acedatacloud/x402-client) | | PyPI SDK | [https://pypi.org/project/acedatacloud/](https://pypi.org/project/acedatacloud/) | | PyPI Cliente X402 | [https://pypi.org/project/acedatacloud-x402/](https://pypi.org/project/acedatacloud-x402/) | 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. | Capacidade | Status | Descrição | | - | - | - | | Capacidades do Facilitator | Disponível | `https://facilitator.acedata.cloud/.well-known/x402` retorna redes de pagamento e pontos finais de protocolo. | | API 402 `accepts` | Disponível | Solicitações não pagas retornarão requisitos de pagamento disponíveis para Base, SKALE e Solana. | | SDK TypeScript | Disponível | `@acedatacloud/sdk` e `@acedatacloud/x402-client` podem lidar automaticamente com 402, assinaturas e tentativas. | | SDK Python | Disponível | `acedatacloud` e `acedatacloud-x402` podem lidar automaticamente com 402, assinaturas e tentativas. | | Base `exact` | Validado em cadeia | Adequado para API de valor fixo e pagamento de pedidos. | | Base `upto` | Validado em cadeia | Adequado para APIs de medição pós-consumo, atualmente a única rede que oferece `upto`. | | SKALE `exact` | Validado em cadeia | Adequado para cenários de pagamento EVM com baixo custo de gas. | | Solana `exact` | HTTP paid retry validado | API paid retry validada com resposta do modelo; recomenda-se usar a própria RPC Solana para conciliação. | | Pagamento de Pedidos | Validado em cadeia | Pagamento de pedidos Base `exact` foi concluído com liquidação em cadeia e atualização do status do pedido. | 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. ```text theme={null} pacotes @acedatacloud/sdk@2026.504.2 import ok @acedatacloud/x402-client@2026.531.3 import ok acedatacloud==2026.4.26.1 import ok acedatacloud-x402==2026.5.31.3 import ok API 402 status 402 accepts eip155:8453/exact, eip155:8453/upto, solana:5eykt4.../exact, eip155:1187947933/exact TypeScript SDK content ADC_TS_SDK_X402_OK Python SDK content ADC_PY_SDK_X402_OK Base exact content ADC_BASE_E2E_OK tx 0x408430ab3451bc22a51e510cdb4b063d6b9686724fea7a31fc109af20f5cd2f3 explorer https://basescan.org/tx/0x408430ab3451bc22a51e510cdb4b063d6b9686724fea7a31fc109af20f5cd2f3 SKALE exact content ADC_SKALE_E2E_OK tx 0x9fd09901e74c763325fe118b2bc64765c3fca785b86b24a78b97964384db084f explorer https://skale-base-explorer.skalenodes.com/tx/0x9fd09901e74c763325fe118b2bc64765c3fca785b86b24a78b97964384db084f Base upto content ADC_BASE_UPTO_OK tx 0x4b0b836ce1cd1171cdbc37df1637150b024214ec28e7f6f2d09122f15cbfc036 explorer https://basescan.org/tx/0x4b0b836ce1cd1171cdbc37df1637150b024214ec28e7f6f2d09122f15cbfc036 signed ceiling 95215 atomic USDC transfer value 3 atomic USDC Solana exact HTTP 402 -> HTTP 200 content ADC_SOLANA_E2E_OK chain signature not confirmed in this run Order payment order 78481793-304e-47f7-bc0c-8231aec9cc1e state Finished pay_way X402 tx 0xfec08cc00a159ea1ec692b32faa9bf3d17595a986301169e689d94f58bc44151 explorer https://basescan.org/tx/0xfec08cc00a159ea1ec692b32faa9bf3d17595a986301169e689d94f58bc44151 ``` 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. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.