Перейти к основному содержанию
X402 — это протокол ончейн-платежей на основе HTTP 402 Payment Required. Благодаря возможностям X402 от Ace Data Cloud вызывающая сторона может не создавать API Token, не пополнять баланс аккаунта заранее, а напрямую оплачивать USDC в сети при каждом API-запросе. Этот набор документов организован в порядке реального подключения: сначала выполните один минимальный запрос, затем подключите SDK, после этого изучите сети, тарифные схемы, оплату заказов и Facilitator. Рекомендуется читать сверху вниз согласно таблице ниже.

Рекомендуемый путь подключения

Если вы хотите только вызывать Ace Data Cloud API, в первую очередь используйте официальный SDK:
  • TypeScript: @acedatacloud/sdk + @acedatacloud/x402-client
  • Python: acedatacloud + acedatacloud-x402
Адреса открытых исходных кодов и пакетов: SDK автоматически выполнит шаги первого запроса без аутентификации, разбора 402 Payment Required, вызова payment handler и повторной попытки с PAYMENT-SIGNATURE. Вам нужно лишь подготовить кошелек с USDC и выбрать сеть, которую вы хотите использовать. Если вы хотите, чтобы ваш собственный API также поддерживал прием платежей X402, вам необходимо прочитать документацию Facilitator и понять взаимосвязь между paymentRequirements, paymentPayload, /verify и /settle.

Статус поддержки

Ace Data Cloud X402 прошел проверку на публичном API, официальных SDK, Facilitator и пути ончейн-расчетов. В таблице ниже приведен текущий статус по наиболее часто используемым возможностям при подключении разработчиков. Следующий вывод используется только для демонстрации формата ответов проверенных путей. При фактическом подключении всегда ориентируйтесь на accepts, возвращаемый текущим API.
Пояснение:
  • Пакеты npm и PyPI были установлены и успешно импортированы в чистом окружении.
  • Неоплаченный API-запрос возвращает 402, а accepts содержит доступные способы оплаты для Base и Solana.
  • accepts[].network является идентификатором CAIP-2; при выборе сети клиент должен сопоставлять строку CAIP-2.
  • TypeScript SDK и Python SDK оба могут автоматически обработать 402 и выполнить платный повторный запрос.
  • Base exact, Base upto и оплата заказа имеют публично доступные адреса explorer.
  • Подписанный потолок Base upto составляет 95215 atomic USDC, фактический settlement составляет 3 atomic USDC, что демонстрирует особенность постоплатного измерения с расчётом по фактическому использованию.
  • Для Solana exact проверены HTTP 402 -> HTTP 200 и вывод модели. Поскольку запросы к публичному RPC могут ограничиваться по частоте, для строгой сверки рекомендуется использовать собственный Solana RPC или записи о settlement со стороны платформы для подтверждения подписи транзакции.

Примечания по интеграции

При интеграции разработчикам следует в первую очередь обращать внимание на требования к оплате в реальном времени, возвращаемые текущим запросом, а не копировать примерные суммы или адреса из документации:
  • accepts[].maxAmountRequired — максимальная сумма, которая может быть подписана для текущего запроса.
  • accepts[].asset — контракт USDC или mint, который должен использоваться для этого запроса.
  • accepts[].extra.chainId、accepts[].extra.facilitatorAddress и accepts[].extra.verifyingContract участвуют в подписи EVM typed data.
  • Для upto кошелёк должен сначала авторизовать Permit2 для USDC целевой сети; при отсутствии авторизации будет возвращён PERMIT2_ALLOWANCE_REQUIRED.
  • Если явно требуется использовать постоплатное измерение, передайте preferScheme: 'upto' в TypeScript SDK; в противном случае SDK выберет первое доступное requirement, возвращённое сервером для этой сети.

Диапазон, который можно публично проверить

Перед интеграцией можно сначала проверить эти публичные точки входа и поведение SDK:
  • API-запрос без Authorization или PAYMENT-SIGNATURE вернёт 402 Payment Required; accepts в ответе является единственным основанием для подписи данного запроса.
  • TypeScript SDK и Python SDK оба предоставляют payment handler; транспортный слой SDK после получения 402 вызовет handler и повторит запрос один раз.
  • https://facilitator.acedata.cloud/.well-known/x402:возвращает сети, scheme и протокольные конечные точки, поддерживаемые Facilitator; цена API по-прежнему определяется 402, возвращаемым целевым запросом в реальном времени.
  • https://facilitator.acedata.cloud/supported:возвращает сети и scheme, поддерживаемые Facilitator.
  • Репозиторий X402Client содержит расширенные инструменты ончейн-проверки, которые могут использоваться для подтверждения подписи, повторной попытки и поведения settlement; вывод инструментов не заменяет accepts, возвращаемый онлайн API.
upto относится к постоплатному измерительному settlement и подходит для API, таких как чат-дополнения и вызовы моделей, где фактическое использование становится известно только после ответа. В настоящее время только Base предоставляет upto; если проверка подписи не удалась, проверьте, соответствуют ли chain id, адрес facilitator, spender, контракт USDC и Permit2 allowance ответу 402.