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:PAYMENT-SIGNATURE. Структура (фрагмент):
x402Version: 2, а объект accepted объявляет выбранные для этого раза scheme и network (идентификатор CAIP-2).
preferScheme / prefer_scheme используется для выбора предпочтения, когда сервер одновременно предоставляет несколько scheme. Если сервер публикует только exact, это поле будет проигнорировано; если задано upto, но сервер его не публикует, произойдёт откат к первому совпадающему варианту.
II. TypeScript: два способа — браузерный кошелёк + серверный viem
Установка
Полная сигнатура createX402PaymentHandler
(ctx) => Promise<{ headers: Record<string, string> }>, что точно соответствует сигнатуре хука paymentHandler SDK.
Вариант 1: браузер (MetaMask / WalletConnect)
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-levelsignEVMUptoPaymentand wire together theaccepts → signed envelope → PAYMENT-SIGNATURE headerpath yourself, bypassing the SDK hook; however, it is still recommended to prioritizecreateX402PaymentHandler, so you do not have to maintain protocol upgrades yourself.
Usage 3: Solana
exact scheme is exposed, so preferScheme does not take effect on Solana.
III. Python: Private Key Mode
Python’sacedatacloud-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
EVM (Base)
Solana
One-Time Approve (EVM First Time Only)
X402 on EVM Base uses Permit2, requiring the wallet to perform a one-timeMaxUint256 approve for USDC to the Permit2 contract. acedatacloud-x402 includes approve_permit2:
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).- No
apiTokenwas passed, and SDK construction does not throw an error, proving that X402 mode is indeed a valid alternative to a token. createX402PaymentHandlerreturns 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-sidecreate_x402_payment_handlerperforms the same verification — the function return value is callable, and constructingAceDataCloud(...)does not throw an error when injectingpayment_handler=.... The semantics are aligned on both sides.
V. Comparison with “Bearer Token Mode”
VI. Распространённые ошибки
- Для chat-классов обязательно
preferScheme=upto: использованиеexactзаставит facilitator списывать USDC поmaxAmountRequired(а не по фактическому потреблению). - На стороне Node не передавайте голый приватный ключ в
createX402PaymentHandler: TS-пакет не принимает{ privateKey }, его обязательно нужно обернуть в EIP-1193 provider (рекомендуется viemWalletClient). - Первый вызов требует двойной подписи: первая подпись — Permit2 approve (он-чейн, с gas), вторая подпись — X402 envelope (не он-чейн). В последующих вызовах остаётся только вторая.
- В Solana нет концепции Permit2: авторизация перевода SPL token подписывается напрямую, approve не требуется; однако в настоящее время в сети Solana поддерживается только
exact. - Различайте ошибки бизнеса и ошибки платежа: 402 → сбой handler выбрасывает
X402SignError(конкретный тип зависит от сети); ошибки бизнес-интерфейса после последующей повторной отправки (401 / 422 / 5xx) по-прежнему классифицируются как обычные исключения SDK. - Самый стабильный способ адаптации
viem:evmProvider: walletClient as anyлишается проверки типов, но обладает наилучшей совместимостью; если нужно сохранить типы, отдельно оберните.transport.requestиз viem в объект{ request }и передайте его.

