Перевірка публічної точки входу
Декларація можливостей 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)
Запуск розширених інструментів перевірки X402Client
Репозиторій X402Client надає розширені інструменти перевірки, які можна використовувати для підтвердження вибору відповіді 402, генерації підпису, paid retry та ончейн settlement. Вони потребують funded wallet, RPC, приватного ключа й залежностей для розробки. Для звичайної інтеграції в бізнес-застосунок рекомендується передусім використовувати TypeScript або Python SDK; запускайте ці інструменти лише тоді, коли потрібно локалізувати проблеми з підписом або ончейн-розрахунком. Адреса репозиторію: https://github.com/AceDataCloud/X402Client- Відповідь 402 першого запиту.
- Вибрану payment requirement.
- Підсумок підписаного
PAYMENT-SIGNATURE. - HTTP-статус і тіло відповіді після повторної спроби.
- Ончейн settlement transaction або причину помилки Facilitator у разі невдачі.
PAYMENT-SIGNATURE до систем журналювання чи в тікети.
Приклад результатів перевірки публічного API:
- Base
exact, Solanaexactі Baseuptoусі виконали paid retry від HTTP 402 до HTTP 200. - Ончейн-транзакцію Base
exactможна знайти в BaseScan, а сума розрахунку становить95215atomic USDC. - Ліміт підпису Base
uptoстановить95215atomic USDC, але фактичний ончейн settlement становить3atomic USDC, що означає списання за фактичним використанням при обліку після використання. - Для шляху Solana підтверджено paid retry і виведення моделі. Публічний RPC може обмежувати частоту запитів; якщо потрібна сувора ончейн-звірка, використовуйте власний Solana RPC або підтвердіть підпис транзакції через записи розрахунків на стороні платформи.
SDK smoke test
Розширені інструменти перевірки використовуються для перевірки підписів і ончейн-розрахунків. Бізнес-сторона також має виконати SDK smoke test, щоб підтвердити, що код застосунку може автоматично обробляти 402 через payment handler. Нижче показано лише основні фрагменти; для повного коду потрібно додати wallet, provider та import. TypeScript:exact і здійснюють розрахунок за фіксованою сумою, вказаною в котируванні 402. Chat completions належать до сценаріїв із вимірюванням за token, тому для робочої інтеграції рекомендується передавати preferScheme: 'upto' (у Python — prefer_scheme="upto"), щоб здійснювати розрахунок за фактичним використанням.
Об’єкт, який повертає Python SDK, є dict; для читання вмісту можна використовувати res["choices"][0]["message"]["content"].
E2E оплати замовлення
Оплата замовлення використовує платформний APIplatform.acedata.cloud і потребує токена облікового запису платформи. Повний ланцюг такий: створення Pending замовлення, POST /api/v1/orders/{order_id}/pay/ запускає 402, після чого виконується повторна спроба з PAYMENT-SIGNATURE.
Приклад результатів перевірки оплати замовлення на невелику суму:
Наведені нижче записи транзакцій є історичними зразками фактичних тестів за старою політикою; суми й хеші транзакцій збережено без змін. Нові замовлення X402 більше не мають знижок за способом оплати; використовуйте amount із поточної відповіді 402 як основу для підпису й оплати.
- Після створення замовлення його статус —
Pending, а ціна —1.26. - Перший запит
pay/повертає HTTP 402, уacceptsє Baseexactі Solanaexact, суми обох становлять1200000atomic USDC. - Після повторної спроби з Base
PAYMENT-SIGNATUREповертається HTTP 200, статус замовлення змінюється наFinished, аpay_way—X402. - Після декодування
PAYMENT-RESPONSEвідображаютьсяsuccess=True、network=base, а також той самий хеш транзакції. - На BaseScan статус транзакції —
1, сума переказу —1200000atomic USDC, тобто1.2USDC. - Ціна створення
1.26була сплачена протягом періоду старої політики знижок на X402, остаточна сума підпису та розрахунку становить1.2USDC.
Authorization: Bearer {platform_token}, або замовлення не належить поточному обліковому запису, збій відбудеться на рівні прав доступу платформи; це відрізняється від безоблікового X402 API при прямому виклику x402.acedata.cloud.
Поширені помилки
Контрольний список Base upto
upto наразі доступний лише на Base (eip155:8453). Оскільки підпис upto прив’язує більше параметрів EVM typed data, під час інтеграції слід особливо перевірити, що поточні поля у відповіді 402 повністю збігаються з клієнтським підписом.
upto повертає invalid_upto_evm_payload_invalid_signature, першочергово перевірте:
extra.chainIdу записіeip155:8453+upto, який повертає API (має бути8453).extra.facilitatorAddress, який повертає API.- Адресу Base
uptofacilitator, яку повертаєhttps://facilitator.acedata.cloud/supported. - Permit2 domain, spender, контракт USDC та обліковий запис підпису.
- Чи гаманець уже виконав approve Permit2 для Base USDC.
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і зберігайте публічний технічний код для пошуку службою підтримки.

