Перейти к основному содержанию
X402 — это предложенный Coinbase протокол ончейн-платежей «оплата по HTTP 402»: сервер возвращает 402 Payment Required на запросы без token, прикладывая поле accepts: [...] со списком принимаемых сетей / активов / цен; клиент локально подписывает авторизацию (на EVM это Permit2 / EIP-712, на Solana — авторизация перевода SPL token), помещает base64-encoded envelope в заголовок PAYMENT-SIGNATURE и отправляет запрос повторно. После проверки сервер действительно выполняет ончейн-расчёт, а затем возвращает бизнес-результат.
X402-клиент Ace Data Cloud напрямую вызывает целевой API и использует возвращаемые этим запросом в реальном времени 402 Payment Required и accepts как основу для цены и подписи. Платёжные возможности Facilitator можно проверить через /.well-known/x402.
И @acedatacloud/sdk, и acedatacloud предоставляют хук paymentHandler: когда запрос, отправленный самим SDK, получает 402, вызывается внедрённый вами handler для получения заголовка PAYMENT-SIGNATURE, после чего исходный запрос отправляется повторно. Используйте @acedatacloud/x402-client / acedatacloud-x402 вместе с SDK, и весь процесс будет полностью прозрачен для бизнес-кода — вам достаточно вызвать client.openai.chat.completions.create(...), внешне это выглядит точно так же, как режим token, но под капотом это оплата за вызовы без необходимости предварительного пополнения. В этой статье:
  • Реально пройдена TS-цепочка «без token + внедрение X402 handler» (проверка T12)
  • Перечислены различия между двумя цепочками подписания EVM / Solana
  • Приведены три адаптации: режим приватного ключа viem, режим браузерного кошелька и Python-режим EVMAccountSigner
  • Разъяснено легко вызывающее проблемы поле preferScheme / prefer_scheme

I. Обзор протокола (обязательно к прочтению)

Один успешный X402-вызов включает 3 HTTP RTT:
X402 envelope — это JSON, который после base64-кодирования помещается в заголовок PAYMENT-SIGNATURE. Структура (фрагмент):
На верхнем уровне envelope находится x402Version: 2, а объект accepted объявляет выбранные для этого раза scheme и network (идентификатор CAIP-2). preferScheme / prefer_scheme используется для выбора предпочтения, когда сервер одновременно предоставляет несколько scheme. Если сервер публикует только exact, это поле будет проигнорировано; если задано upto, но сервер его не публикует, произойдёт откат к первому совпадающему варианту.

II. TypeScript: два способа — браузерный кошелёк + серверный viem

Установка

Протестированные номера версий:

Полная сигнатура createX402PaymentHandler

Возвращаемое значение — (ctx) => Promise&lt;{ headers: Record<string, string> }>, что точно соответствует сигнатуре хука paymentHandler SDK.

Вариант 1: браузер (MetaMask / WalletConnect)

При первом вызове браузер покажет два запроса на подпись: первый — одноразовый approve Permit2 для USDC (сумма — MaxUint256, записывается в сеть); второй — EIP-712-подпись X402 envelope (не записывается в сеть, нужна только для проверки facilitator). В последующих вызовах потребуется только вторая подпись, то есть по ощущениям это «один клик подписи → получить результат».

Вариант 2: Node-сервер + приватный ключ viem (подходит для бэкенда / CLI)

@acedatacloud/x402-client на TS-стороне принимает только EIP-1193 provider — он не управляет приватными ключами напрямую. В сценариях Node / CLI стандартный подход — упаковать приватный ключ в WalletClient с помощью viem, а затем использовать EIP-1193-адаптацию из @ethereumjs/util или внутреннюю адаптацию viem.
If you feel viem’s EIP-1193 adaptation is not stable enough, you can also use the lower-level signEVMUptoPayment and wire together the accepts → signed envelope → PAYMENT-SIGNATURE header path yourself, bypassing the SDK hook; however, it is still recommended to prioritize createX402PaymentHandler, so you do not have to maintain protocol upgrades yourself.

Usage 3: Solana

On the Solana chain, currently only the exact scheme is exposed, so preferScheme does not take effect on Solana.

III. Python: Private Key Mode

Python’s acedatacloud-x402 uses the approach of signing directly with the private key (without an EIP-1193 abstraction), making it more suitable for servers / task executors.

Installation

Tested version numbers:

EVM (Base)

Solana

One-Time Approve (EVM First Time Only)

X402 on EVM Base uses Permit2, requiring the wallet to perform a one-time MaxUint256 approve for USDC to the Permit2 contract. acedatacloud-x402 includes approve_permit2:
This transaction only needs to be sent once; all subsequent X402 EVM payments use this authorization. Solana does not need it.

IV. Real Runtime Verification

Test objective: the TS SDK does not pass a token, injects an X402 handler, and can normally construct and initiate requests (a lightweight verification that does not consume real on-chain USDC).
Output:
The results indicate:
  • No apiToken was passed, and SDK construction does not throw an error, proving that X402 mode is indeed a valid alternative to a token.
  • createX402PaymentHandler returns a function (hook), which the SDK calls only upon receiving a 402 response.
  • The end-to-end test for actual on-chain payment was not included in this tutorial because it involves real USDC deductions; you can refer to the e2e example in the X402 Integration Guide.
The Python-side create_x402_payment_handler performs the same verification — the function return value is callable, and constructing AceDataCloud(...) does not throw an error when injecting payment_handler=.... The semantics are aligned on both sides.

V. Comparison with “Bearer Token Mode”

VI. Распространённые ошибки

  1. Для chat-классов обязательно preferScheme=upto: использование exact заставит facilitator списывать USDC по maxAmountRequired (а не по фактическому потреблению).
  2. На стороне Node не передавайте голый приватный ключ в createX402PaymentHandler: TS-пакет не принимает { privateKey }, его обязательно нужно обернуть в EIP-1193 provider (рекомендуется viem WalletClient).
  3. Первый вызов требует двойной подписи: первая подпись — Permit2 approve (он-чейн, с gas), вторая подпись — X402 envelope (не он-чейн). В последующих вызовах остаётся только вторая.
  4. В Solana нет концепции Permit2: авторизация перевода SPL token подписывается напрямую, approve не требуется; однако в настоящее время в сети Solana поддерживается только exact.
  5. Различайте ошибки бизнеса и ошибки платежа: 402 → сбой handler выбрасывает X402SignError (конкретный тип зависит от сети); ошибки бизнес-интерфейса после последующей повторной отправки (401 / 422 / 5xx) по-прежнему классифицируются как обычные исключения SDK.
  6. Самый стабильный способ адаптации viem: evmProvider: walletClient as any лишается проверки типов, но обладает наилучшей совместимостью; если нужно сохранить типы, отдельно оберните .transport.request из viem в объект { request } и передайте его.

Узнать больше