Перейти к основному содержанию
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. Чат-дополнения относятся к сценариям с учётом по токенам; при формальной интеграции рекомендуется передавать 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 status;
  • вывод модели или task ID в ответе;
  • ссылку на settlement transaction;
  • Gateway trace ID или ID записи использования платформы.
Не сохраняйте приватные ключи, полный PAYMENT-SIGNATURE, полную EIP-712 signature или мнемоническую фразу.

Структурированные ошибки оплаты

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