Перейти до основного вмісту
X402 — це запропонований Coinbase ончейн-протокол платежів «з тарифікацією за HTTP 402»: сервер повертає 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, режим браузерного гаманця, режим 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 стандартний підхід — використати viem, щоб обгорнути приватний ключ у WalletClient, а потім використати @ethereumjs/util або внутрішній EIP-1193-адаптер viem.
Якщо вважаєте, що адаптація EIP-1193 у viem недостатньо стабільна, також можна піти нижчорівневим шляхом через signEVMUptoPayment, самостійно зібрати шлях accepts → signed envelope → PAYMENT-SIGNATURE header, пропустивши SDK-хук; утім, усе ж рекомендується насамперед використовувати createX402PaymentHandler, щоб не підтримувати оновлення протоколу самостійно.

Використання 3: Solana

У мережі Solana наразі доступна лише схема exact, тому preferScheme у Solana не працює.

III. Python: режим приватного ключа

acedatacloud-x402 у Python використовує шлях безпосереднього підписання приватним ключем (без абстракції EIP-1193), що більше підходить для серверної частини / виконавців завдань.

Встановлення

Перевірені номери версій:

EVM (Base)

Solana

Одноразовий approve (лише під час першого використання EVM)

У EVM Base X402 використовує Permit2, тому гаманцю потрібно один раз виконати approve MaxUint256 для USDC на контракт Permit2. acedatacloud-x402 містить вбудований approve_permit2:
Цю транзакцію потрібно надіслати лише один раз, після чого всі платежі X402 EVM використовуватимуть цей дозвіл. Для Solana це не потрібно.

IV. Перевірка реального запуску

Мета тестування: TS SDK без передавання token, з ін’єкцією X402 handler, може нормально створювати та надсилати запити (полегшена перевірка без витрат реального ончейн USDC).
Вивід:
Результат показує:
  • apiToken не передається, і створення SDK не викликає помилки, що доводить: режим X402 справді є легітимною заміною token.
  • createX402PaymentHandler повертає функцію (хук), яку SDK викличе лише після отримання 402.
  • Наскрізний тест із реальною ончейн-оплатою не додано до цього посібника, оскільки він передбачає реальне списання USDC; можна звернутися до прикладу e2e у посібнику з інтеграції X402.
На стороні Python create_x402_payment_handler також пройшов таку саму перевірку — функція повертає callable, а створення AceDataCloud(...) із передаванням payment_handler=... не викликає помилки. Семантика на обох сторонах узгоджена.

V. Порівняння з «режимом Bearer token»

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 transfer, approve не потрібен; але наразі в мережі Solana підтримується лише exact.
  5. Розрізняйте бізнес-помилки та помилки платежу: 402 → збій handler викидає X402SignError (конкретний тип залежить від мережі); помилки бізнес-інтерфейсу після повторного надсилання (401 / 422 / 5xx) усе ще класифікуються як звичайні винятки SDK.
  6. Найстабільніший спосіб адаптації viem: evmProvider: walletClient as any втратить перевірку типів, але має найкращу сумісність; якщо потрібно зберегти типізацію, окремо обгорніть .transport.request viem в об’єкт { request } і передайте його.

Дізнатися більше