Перейти до основного вмісту
X402 охоплює HTTP, SDK, підписи, Facilitator і ончейн-транзакції. Під час усунення проблем із підписами або розрахунками рекомендується поетапно перевіряти в порядку «публічна точка входу -> відповідь 402 -> SDK payment handler -> ончейн settlement». Цей посібник описує способи перевірки кожного рівня та перелічує поширені помилки.

Перевірка публічної точки входу

Декларація можливостей Facilitator:
Якщо повертаються facilitator, supportedKinds і протокольні ендпоінти, це означає, що метадані можливостей у нормі. Виявлення API-ресурсів виведено з експлуатації; безпосередньо викликайте цільовий API та орієнтуйтеся на відповідь 402 у реальному часі. Підтримувані можливості Facilitator:
Якщо повертається kinds, це означає, що точка входу Facilitator працює нормально.

Перевірка 402 accepts

Надішліть неавторизований запит, який не списує кошти:
Перевірте, чи містить повернений accepts мережу, яку ви хочете використовувати. network є ідентифікатором CAIP-2:
  • eip155:8453 + exact(Base)
  • eip155:8453 + upto(Base, облік після використання)
  • solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp + exact(Solana)
Якщо цільова мережа відсутня, це означає, що цей API або поточне середовище не налаштовані з відповідним способом отримання платежів X402.

Запуск розширених інструментів перевірки X402Client

Репозиторій X402Client надає розширені інструменти перевірки, які можна використовувати для підтвердження вибору відповіді 402, генерації підпису, paid retry та ончейн settlement. Вони потребують funded wallet, RPC, приватного ключа й залежностей для розробки. Для звичайної інтеграції в бізнес-застосунок рекомендується передусім використовувати TypeScript або Python SDK; запускайте ці інструменти лише тоді, коли потрібно локалізувати проблеми з підписом або ончейн-розрахунком. Адреса репозиторію: https://github.com/AceDataCloud/X402Client
Base:
Solana:
Інструменти перевірки зазвичай виводять:
  1. Відповідь 402 першого запиту.
  2. Вибрану payment requirement.
  3. Підсумок підписаного PAYMENT-SIGNATURE.
  4. HTTP-статус і тіло відповіді після повторної спроби.
  5. Ончейн settlement transaction або причину помилки Facilitator у разі невдачі.
Не надсилайте приватні ключі або повний PAYMENT-SIGNATURE до систем журналювання чи в тікети. Приклад результатів перевірки публічного API:
Пояснення:
  • Base exact, Solana exact і Base upto усі виконали paid retry від HTTP 402 до HTTP 200.
  • Ончейн-транзакцію Base exact можна знайти в BaseScan, а сума розрахунку становить 95215 atomic USDC.
  • Ліміт підпису Base upto становить 95215 atomic USDC, але фактичний ончейн settlement становить 3 atomic USDC, що означає списання за фактичним використанням при обліку після використання.
  • Для шляху Solana підтверджено paid retry і виведення моделі. Публічний RPC може обмежувати частоту запитів; якщо потрібна сувора ончейн-звірка, використовуйте власний Solana RPC або підтвердіть підпис транзакції через записи розрахунків на стороні платформи.

SDK smoke test

Розширені інструменти перевірки використовуються для перевірки підписів і ончейн-розрахунків. Бізнес-сторона також має виконати SDK smoke test, щоб підтвердити, що код застосунку може автоматично обробляти 402 через payment handler. Нижче показано лише основні фрагменти; для повного коду потрібно додати wallet, provider та import. TypeScript:
Python:
Якщо модель повертає фіксований рядок згідно з вимогами, це означає, що SDK, payment handler, Gateway, Facilitator і цільовий API з’єднані в один ланцюг. Наведені вище два smoke test використовують Base exact і здійснюють розрахунок за фіксованою сумою, вказаною в котируванні 402. Chat completions належать до сценаріїв із вимірюванням за token, тому для робочої інтеграції рекомендується передавати preferScheme: 'upto' (у Python — prefer_scheme="upto"), щоб здійснювати розрахунок за фактичним використанням. Об’єкт, який повертає Python SDK, є dict; для читання вмісту можна використовувати res["choices"][0]["message"]["content"].

E2E оплати замовлення

Оплата замовлення використовує платформний API platform.acedata.cloud і потребує токена облікового запису платформи. Повний ланцюг такий: створення Pending замовлення, POST /api/v1/orders/{order_id}/pay/ запускає 402, після чого виконується повторна спроба з PAYMENT-SIGNATURE. Приклад результатів перевірки оплати замовлення на невелику суму:
Наведені нижче записи транзакцій є історичними зразками фактичних тестів за старою політикою; суми й хеші транзакцій збережено без змін. Нові замовлення X402 більше не мають знижок за способом оплати; використовуйте amount із поточної відповіді 402 як основу для підпису й оплати.
Пояснення результатів:
  • Після створення замовлення його статус — Pending, а ціна — 1.26.
  • Перший запит pay/ повертає HTTP 402, у accepts є Base exact і Solana exact, суми обох становлять 1200000 atomic USDC.
  • Після повторної спроби з Base PAYMENT-SIGNATURE повертається HTTP 200, статус замовлення змінюється на Finished, а pay_way — X402.
  • Після декодування PAYMENT-RESPONSE відображаються success=True、network=base, а також той самий хеш транзакції.
  • На BaseScan статус транзакції — 1, сума переказу — 1200000 atomic USDC, тобто 1.2 USDC.
  • Ціна створення 1.26 була сплачена протягом періоду старої політики знижок на X402, остаточна сума підпису та розрахунку становить 1.2 USDC.
Якщо під час оплати замовлення немає Authorization: Bearer {platform_token}, або замовлення не належить поточному обліковому запису, збій відбудеться на рівні прав доступу платформи; це відрізняється від безоблікового X402 API при прямому виклику x402.acedata.cloud.

Поширені помилки

Контрольний список Base upto

upto наразі доступний лише на Base (eip155:8453). Оскільки підпис upto прив’язує більше параметрів EVM typed data, під час інтеграції слід особливо перевірити, що поточні поля у відповіді 402 повністю збігаються з клієнтським підписом.
Якщо Base upto повертає invalid_upto_evm_payload_invalid_signature, першочергово перевірте:
  1. extra.chainId у записі eip155:8453 + upto, який повертає API (має бути 8453).
  2. extra.facilitatorAddress, який повертає API.
  3. Адресу Base upto facilitator, яку повертає https://facilitator.acedata.cloud/supported.
  4. Permit2 domain, spender, контракт USDC та обліковий запис підпису.
  5. Чи гаманець уже виконав approve Permit2 для Base USDC.
Digest підпису upto одночасно прив’язує Permit2 domain, chain ID, spender, адресу одержувача, адресу facilitator і validAfter. Якщо будь-який із них не збігається, Facilitator відновить неправильний signer, що призведе до повернення invalid signature. Якщо все це збігається, але все одно повертається 402, наступним кроком перевірте Permit2 allowance; за відсутності авторизації повертається PERMIT2_ALLOWANCE_REQUIRED.

Збереження інформації для перевірки

Одна повна перевірка щонайменше зберігає:
  • API path і стислий виклад тіла запиту;
  • вибрані network і scheme;
  • maxAmountRequired;
  • адресу гаманця payer;
  • остаточний HTTP статус;
  • модельний вивід або ID завдання у відповіді;
  • посилання на settlement transaction;
  • Gateway trace ID або ID запису використання платформи.
Не зберігайте приватні ключі, повний PAYMENT-SIGNATURE, повний EIP-712 signature або seed-фразу.

Структуровані помилки оплати

Помилки X402 після підпису повертатимуть стабільні code, безпечні параметри інтерполяції, етап і прапорець повторної спроби у extensions.acedatacloud.paymentError. Першочергово використовуйте цю структуру для діагностики, не аналізуйте англійський верхньорівневий error і не просіть користувача надати підпис гаманця або оригінальний текст симуляції в ланцюгу.
  • charged: false: перевірка була явно відхилена до settlement, цього разу списання не було ініційовано.
  • Не містить charged: результат невідомий або вже перейшов до етапу settlement, спочатку перевірте замовлення та стан у ланцюгу, прямо повторювати оплату заборонено.
  • settlement_pending: поки що не повторюйте оплату, спочатку оновіть замовлення або зверніться до підтримки.
  • Нерозпізнаний code: обробляйте як payment_failed і зберігайте публічний технічний код для пошуку службою підтримки.