Saltar para o conteúdo principal
TypeScript é uma das formas mais recomendadas de integrar o Ace Data Cloud X402. O SDK oficial é responsável por chamadas de API comuns, polling de tarefas, tratamento de erros e tentativas automáticas; @acedatacloud/x402-client é responsável por assinar o cabeçalho de solicitação PAYMENT-SIGNATURE ao encontrar 402 Payment Required. Endereços do código-fonte e dos pacotes:

Instalar dependências

Se usar Base, é necessária capacidade de assinatura EVM:
Se usar Solana, é necessário um adaptador de carteira Solana ou @solana/web3.js:
Saída de verificação de instalação e importação de um projeto npm limpo:
Explicação dos resultados:
  • @acedatacloud/sdk e @acedatacloud/x402-client podem ambos ser instalados pelo npm e importados pelo Node.js.
  • ethers é usado para assinatura de typed data EVM, e @solana/web3.js é usado para construção de transações Solana.

Exemplo Base

No navegador, é possível usar window.ethereum diretamente. No Node.js, é possível envolver ethers.Wallet em um provider no estilo EIP-1193.

Exemplo de carteira no navegador

Ao usar MetaMask, Coinbase Wallet ou WalletConnect em aplicações frontend, normalmente o provider EIP-1193 é passado diretamente:
A carteira do navegador exibirá uma confirmação de assinatura. O que o usuário assina não é uma mensagem arbitrária, mas o requisito de pagamento retornado pela API: o endereço de recebimento, o contrato USDC, o valor, a validade e o nonce estão todos incluídos na assinatura.

Exemplo Solana

Solana usa SPL USDC TransferChecked. O adaptador de carteira passado precisa expor publicKey e signAndSendTransaction.
O caminho Solana atualmente suporta apenas exact, e não suporta upto. Se a API retornar vários accepts, o handler escolherá aquele com network = 'solana'. O caminho Solana foi verificado na mesma API pública, onde a nova tentativa paga pode retornar HTTP 200 e ADC_SOLANA_E2E_OK. Consultas RPC públicas podem sofrer limitação de taxa, por isso este texto não inclui o hash da tx Solana; quando for necessário conciliar on-chain, use seu próprio RPC Solana ou confirme pelos registros do console.

Escolher exact ou upto

O handler TypeScript atual escolherá o primeiro payment requirement da rede correspondente retornado pelo servidor. As APIs do Ace Data Cloud normalmente colocam o exact da mesma rede antes de upto, portanto, se você deseja explicitamente usar medição posterior, precisa passar preferScheme: 'upto'. Exemplo:
Se o servidor não retornar um requirement upto para essa rede, o handler voltará automaticamente para o primeiro requirement disponível dessa rede, normalmente exact. upto requer uma autorização Permit2 única. Atualmente, upto é fornecido apenas na Base, portanto, basta fazer uma autorização para o USDC da Base:
O upto da Base concluiu a verificação da API pública: HTTP 402 -> HTTP 200, e a tx de settlement posterior é 0x4b0b836ce1cd1171cdbc37df1637150b024214ec28e7f6f2d09122f15cbfc036. A saída completa está na explicação do plano de cobrança.

O que o SDK faz

O transport de @acedatacloud/sdk executará um payment handler uma vez ao receber 402:
O handler retornado por @acedatacloud/x402-client irá:
  1. Selecionar o payment requirement da rede de destino em ctx.accepts.
  2. Construir uma assinatura EVM EIP-712 ou uma transaction de transferência Solana de acordo com a rede.
  3. Serializar o envelope em Base64.
  4. Retornar { headers: { 'PAYMENT-SIGNATURE': '<base64>' } }.
  5. O SDK tenta novamente automaticamente com o corpo da solicitação original.
Isso significa que o código de negócio só precisa ser escrito como uma chamada SDK comum, sem precisar tratar manualmente as tentativas novamente após 402.