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

​
Рекомендуемый путь интеграции

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

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

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

​
Важные моменты при подключении

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

​
Область, которую можно публично проверить

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