Saltar para o conteúdo principal
O Ace Data Cloud X402 atualmente gira em torno da liquidação em USDC, suportando dois tipos de rede: EVM e Solana. Os métodos de assinatura, endereços de ativos, comportamento de gas e cenários aplicáveis variam entre as redes, sendo necessário escolher a rede antes da integração.

Os identificadores de rede usam CAIP-2

O accepts[].network do x402 v2 é um identificador CAIP-2, e não abreviações como base ou solana. Ao corresponder redes, o cliente deve comparar pelas strings CAIP-2:

Matriz de suporte

Atualmente, o upto é fornecido apenas na Base. Os itens realmente disponíveis estão sujeitos ao accepts retornado pela API. Você também pode consultar o Facilitator:
Retorno do Facilitator /supported:
Explicação dos resultados:
  • O exact da Base e da Solana é um caminho de pagamento de valor fixo.
  • Apenas a Base fornece o caminho de medição posterior upto, que depende da aprovação do Permit2.
  • O extra.facilitatorAddress na entrada upto é o endereço que o cliente deve gravar no witness ao assinar e deve ser consistente com o valor retornado pelo servidor.

Base

A Base usa o contrato oficial de USDC:
No esquema exact, o cliente assina o EIP-712 TransferWithAuthorization. O conteúdo da assinatura inclui:
  • from: endereço da carteira pagadora
  • to: endereço de recebimento do Ace Data Cloud
  • value: valor deste pagamento
  • validAfter / validBefore: janela de validade da assinatura
  • nonce: nonce aleatório de 32 bytes
Após verificar a assinatura, o Facilitator chamará o transferWithAuthorization do USDC on-chain para concluir a transferência. A Base é a rede de integração formal mais recomendada, especialmente adequada para a medição posterior upto, pois os ecossistemas de Permit2, USDC e carteiras são mais maduros. Exemplo de resultado de verificação do Base exact:
Explicação dos resultados:
  • A nova tentativa paga da API retorna o conteúdo do modelo ADC_BASE_E2E_OK.
  • A transação on-chain já pode ser consultada no BaseScan, e o número do bloco é 46726299.
  • 95215 atomic USDC corresponde a 0.095215 USDC, que é o valor real liquidado desta chamada de API.
Resultado da execução do programa de pagamento Base exact para pedidos:
Explicação dos resultados:
  • O estado final do pedido na plataforma é Finished.
  • O pay_id do pedido grava o mesmo hash de transação da Base.
  • 1200000 atomic USDC corresponde a 1.2 USDC, que é o valor histórico efetivamente pago por este pedido de 10 Credits sob a política antiga; novos pedidos não recebem mais desconto adicional pelo método de pagamento X402, e o valor específico da assinatura está sujeito à resposta 402 desta vez.

Solana

A Solana usa SPL USDC TransferChecked. O cliente constrói uma transação de transferência, assina e envia, e depois coloca a assinatura da transação ou a transação serializada no envelope PAYMENT-SIGNATURE. Características da Solana:
  • Uso de Solana wallet adapter ou chave secreta base58;
  • O ativo é o mint de Solana USDC;
  • Atualmente, apenas exact é suportado;
  • O Facilitator verificará o mint, destination, authority e amount da instrução de transferência.
Se o modo de fee payer da carteira for usado, a carteira enviará diretamente a transação, e o Facilitator será responsável por confirmar a transação e retornar o resultado da liquidação. Exemplo de resultado de verificação do Solana exact:
Explicação dos resultados:
  • A nova tentativa paga já retornou HTTP 200, e o modelo gerou ADC_SOLANA_E2E_OK.
  • Podem ocorrer limites de taxa ao consultar a signature on-chain por meio de RPCs públicos.
  • Como as consultas a RPCs públicos podem sofrer limitação de taxa, o Solana explorer não é incluído aqui. Quando for necessário um processo rigoroso de reconciliação, use seu próprio Solana RPC ou os registros de liquidação da plataforma para confirmar a assinatura da transação.

Como escolher

Independentemente da cadeia escolhida, não codifique preços diretamente no cliente. O preço é determinado pelo accepts[].maxAmountRequired retornado pelo servidor.

Adicionar novas redes EVM

O suporte de código para pagamentos de valor fixo em USDC nativo nas seguintes redes foi disponibilizado, sendo liberado uma a uma por rede. A disponibilidade deve ser baseada no accepts retornado pelo pedido ou pela API; isso não significa que todas as redes já estejam habilitadas em produção. Essas redes suportam apenas exact, e a precisão da moeda é 6. Não use USDC em ponte com o mesmo nome. Ao usar o X402 Client oficial para TypeScript/Python, é possível informar a abreviação da tabela ou o identificador CAIP-2. O cliente usa o ID da cadeia de destino para construir a assinatura; a carteira deve oferecer suporte à rede de destino. A tabela oficial de suporte da carteira de extensão Phantom lista Arbitrum e Polygon; Optimism e Avalanche não estão atualmente incluídas nessa tabela, e é possível usar Rabby ou MetaMask que ofereçam suporte à cadeia de destino. Endereços EVM podem ser iguais em cadeias diferentes, mas os saldos são independentes entre si, e endereços Solana não se aplicam ao USDC EVM. Consulte a tabela de suporte da carteira Phantom.

Entrada em escala de cinza para novas redes

A entrada para novas cadeias fica oculta por padrão. Ao acessar o console ou o Studio, é possível usar ?features=x402-arbitrum para habilitar a cadeia correspondente; vários flags são separados por vírgulas. Para desabilitar uma única cadeia, use ?features=-x402-arbitrum, e para limpar as substituições locais, use ?features=none. As opções são salvas separadamente para cada domínio. A cotação do pedido e a nova tentativa de pagamento usam a mesma opção, e o servidor fará validação independente; os registros de pagamento existentes ainda poderão ser visualizados. Apenas habilitar o flag da página não habilitará uma cadeia que ainda não foi configurada; as redes efetivamente pagáveis continuam sendo determinadas pelo accepts em tempo real.