Перейти к основному содержанию
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 во frontend-приложении обычно напрямую передаётся 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, post-settlement tx — 0x4b0b836ce1cd1171cdbc37df1637150b024214ec28e7f6f2d09122f15cbfc036. Полный вывод приведён в описании схемы биллинга.

Что делает SDK

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