402 Payment Required для запитів без token, додаючи поле accepts: [...] зі списком прийнятних мереж / активів / цін; клієнт локально підписує авторизацію (на EVM це Permit2 / EIP-712, на Solana — авторизація SPL token transfer), поміщає 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-режимі, але під капотом це оплата за виклик без потреби попереднього поповнення.
У цій статті:
- реально пройдено ланцюжок «без token + інʼєкція X402 handler» на TS-боці (перевірка T12)
- перелічено відмінності між двома ланцюжками підпису EVM / Solana
- наведено три адаптації: режим приватного ключа
viem, режим браузерного гаманця, режим PythonEVMAccountSigner - детально пояснено поле
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 стандартний підхід — використати viem, щоб обгорнути приватний ключ у WalletClient, а потім використати @ethereumjs/util або внутрішній EIP-1193-адаптер viem.
Якщо вважаєте, що адаптація EIP-1193 у viem недостатньо стабільна, також можна піти нижчорівневим шляхом черезsignEVMUptoPayment, самостійно зібрати шляхaccepts → signed envelope → PAYMENT-SIGNATURE header, пропустивши SDK-хук; утім, усе ж рекомендується насамперед використовуватиcreateX402PaymentHandler, щоб не підтримувати оновлення протоколу самостійно.
Використання 3: Solana
exact, тому preferScheme у Solana не працює.
III. Python: режим приватного ключа
acedatacloud-x402 у Python використовує шлях безпосереднього підписання приватним ключем (без абстракції EIP-1193), що більше підходить для серверної частини / виконавців завдань.
Встановлення
EVM (Base)
Solana
Одноразовий approve (лише під час першого використання EVM)
У EVM Base X402 використовує Permit2, тому гаманцю потрібно один раз виконати approveMaxUint256 для USDC на контракт Permit2. acedatacloud-x402 містить вбудований approve_permit2:
IV. Перевірка реального запуску
Мета тестування: TS SDK без передавання token, з ін’єкцією X402 handler, може нормально створювати та надсилати запити (полегшена перевірка без витрат реального ончейн USDC).apiTokenне передається, і створення SDK не викликає помилки, що доводить: режим X402 справді є легітимною заміною token.createX402PaymentHandlerповертає функцію (хук), яку SDK викличе лише після отримання 402.- Наскрізний тест із реальною ончейн-оплатою не додано до цього посібника, оскільки він передбачає реальне списання USDC; можна звернутися до прикладу e2e у посібнику з інтеграції X402.
На стороні Pythoncreate_x402_payment_handlerтакож пройшов таку саму перевірку — функція повертає callable, а створенняAceDataCloud(...)із передаваннямpayment_handler=...не викликає помилки. Семантика на обох сторонах узгоджена.
V. Порівняння з «режимом Bearer token»
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 transfer, approve не потрібен; але наразі в мережі Solana підтримується лише
exact. - Розрізняйте бізнес-помилки та помилки платежу: 402 → збій handler викидає
X402SignError(конкретний тип залежить від мережі); помилки бізнес-інтерфейсу після повторного надсилання (401 / 422 / 5xx) усе ще класифікуються як звичайні винятки SDK. - Найстабільніший спосіб адаптації
viem:evmProvider: walletClient as anyвтратить перевірку типів, але має найкращу сумісність; якщо потрібно зберегти типізацію, окремо обгорніть.transport.requestviem в об’єкт{ request }і передайте його.

