Перейти до основного вмісту
TypeScript є одним із найбільш рекомендованих способів інтеграції Ace Data Cloud X402. Офіційний SDK відповідає за звичайні API-виклики, опитування завдань, обробку помилок і автоматичні повторні спроби; @acedatacloud/x402-client відповідає за підписання заголовка запиту PAYMENT-SIGNATURE при виникненні 402 Payment Required. Вихідний код та адреси пакетів:

Встановлення залежностей

Якщо використовується Base, потрібна можливість EVM-підпису:
Якщо використовується Solana, потрібен Solana wallet adapter або @solana/web3.js:
Вивід перевірки встановлення та імпорту в чистому npm-проєкті:
Пояснення результатів:
  • @acedatacloud/sdk і @acedatacloud/x402-client можна встановити з npm та імпортувати через Node.js.
  • ethers використовується для підпису EVM typed data, а @solana/web3.js — для створення Solana transaction.

Приклад Base

У браузері можна безпосередньо використовувати window.ethereum. У Node.js можна обгорнути ethers.Wallet provider’ом у стилі EIP-1193.

Приклад браузерного гаманця

Під час використання MetaMask, Coinbase Wallet або WalletConnect у фронтенд-застосунку зазвичай безпосередньо передається EIP-1193 provider:
Браузерний гаманець покаже підтвердження підпису. Користувач підписує не довільне повідомлення, а вимогу до оплати, повернену API: адреса одержувача, контракт USDC, сума, строк дії та nonce — усе це включено до підпису.

Приклад Solana

Solana використовує SPL USDC TransferChecked. Переданий wallet adapter має надавати publicKey та signAndSendTransaction.
Шлях Solana наразі підтримує лише exact і не підтримує upto. Якщо API повертає кілька accepts, handler вибере елемент із network = 'solana'. Шлях Solana уже перевірено на тому самому публічному API: paid retry може повертати HTTP 200 та ADC_SOLANA_E2E_OK. Запити до публічного RPC можуть мати обмеження швидкості, тому в цій статті не вказано Solana tx hash; якщо потрібна ончейн-звірка, використовуйте власний Solana RPC або підтвердження із записів консолі.

Вибір exact або upto

Поточний TypeScript handler вибирає першу payment requirement для відповідної мережі, повернену сервером. API Ace Data Cloud зазвичай розміщує exact тієї самої мережі перед upto, тому якщо ви точно хочете використовувати післяплатний облік, потрібно передати preferScheme: 'upto'. Приклад:
Якщо сервер не повертає upto requirement для цієї мережі, handler автоматично повернеться до першої доступної requirement для цієї мережі, зазвичай це exact. Для upto потрібна одноразова авторизація Permit2. upto наразі доступний лише в Base, тому потрібно лише один раз надати авторизацію для Base USDC:
Base upto пройшов перевірку на публічному API: HTTP 402 -> HTTP 200, післяплатний settlement tx — 0x4b0b836ce1cd1171cdbc37df1637150b024214ec28e7f6f2d09122f15cbfc036. Повний вивід дивіться в описі схеми виставлення рахунків.

Що робить SDK

Transport @acedatacloud/sdk виконує payment handler один раз при отриманні 402:
Handler, повернутий @acedatacloud/x402-client, виконає:
  1. Вибере payment requirement цільової мережі з ctx.accepts.
  2. Створить EVM EIP-712 підпис або Solana transfer transaction відповідно до мережі.
  3. Серіалізує envelope у Base64.
  4. Поверне { headers: { 'PAYMENT-SIGNATURE': '<base64>' } }.
  5. SDK автоматично повторить спробу з вихідним тілом запиту.
Це означає, що бізнес-код потрібно писати лише як звичайний SDK-виклик, без необхідності вручну обробляти повторні спроби 402.