Перейти к основному содержанию
В этом руководстве на примере минимального API-запроса объясняется полный процесс Ace Data Cloud X402. Цель — не сначала писать сложный код, а сначала понять: почему первый запрос возвращает 402, что содержится в accepts и как PAYMENT-SIGNATURE превращает тот же API-запрос в оплаченный запрос.

Подготовка

Вам нужно подготовить: При вызове Ace Data Cloud API через X402 API Token не требуется. Первый запрос SDK не содержит Authorization, Gateway вернёт 402 Payment Required и требования к оплате; после подписи SDK автоматически повторит попытку.

Установка SDK

Исходный код и адреса пакетов: TypeScript:
Python:
Если нужно использовать Solana, также необходимо установить соответствующие зависимости:
Зависимости Solana signer для версии Python уже включены в acedatacloud-x402. Вывод проверки установки и импорта в чистой временной среде:
Пояснение результатов:
  • Пакеты npm и PyPI являются реально опубликованными пакетами, а не названиями-заглушками из документации.
  • acedatacloud-x402[cli] установит CLI, подкоманда approve-permit2 может использоваться для авторизации Permit2 в сценариях upto.

Первый запрос вернёт 402

Сначала можно использовать curl, чтобы посмотреть, что возвращает неоплаченный запрос. Приведённый ниже пример не приведёт к списанию средств, поскольку он не содержит PAYMENT-SIGNATURE:
Тело ответа будет содержать массив accepts, типичная структура выглядит следующим образом:
То же содержимое challenge также размещается в заголовке ответа PAYMENT-REQUIRED в виде base64, чтобы клиент мог получать требования к оплате без разбора body. Сводка программного вывода неоплаченного запроса к production API выглядит следующим образом:
Пояснение результатов:
  • Первый запрос не содержит Authorization или PAYMENT-SIGNATURE, поэтому возвращается HTTP 402, списание средств не произойдёт.
  • accepts — единственная достоверная основа для подписи этого запроса, содержащая доступные сети, scheme, лимит суммы, адрес получателя и адрес актива.
  • network — идентификатор CAIP-2, клиент при выборе сети должен сопоставлять его по строке CAIP-2.
  • Лимит суммы для этого минимального запроса чата gpt-4o-mini составляет 95215 atomic USDC, то есть 0.095215 USDC.
  • Для каждого запроса следует читать текущий ответ 402, не следует жёстко кодировать примерную сумму в бизнес-коде.
Значение полей:

Выполнение повторной попытки оплаты с помощью SDK

Ниже приведён минимальный пример TypeScript. Он указывает network: 'base', handler выберет requirement для оплаты Base из текущего ответа 402; фактическая сумма и адрес получателя по-прежнему определяются accepts:
За этим кодом происходят четыре шага:
  1. SDK отправляет обычный API-запрос без Authorization.
  2. Gateway возвращает 402 Payment Required и accepts.
  3. createX402PaymentHandler выбирает payment requirement для network = 'base' и подписывает PAYMENT-SIGNATURE.
  4. SDK повторяет попытку с тем же телом запроса, а Gateway вызывает Facilitator для проверки и расчёта, после чего пропускает запрос к целевому API.

Просмотр поддерживаемых возможностей Facilitator

X402 API не зависит от каталога ресурсов. Клиент напрямую вызывает известный API и использует возвращаемые этим запросом в реальном времени 402 Payment Required и accepts как единственное основание для цены и подписи. Объявление возможностей Facilitator находится по адресу:
Оно описывает только /supported, /verify, /settle и текущие включённые платёжные сети, не перечисляя API-ресурсы. Адрес production Facilitator Ace Data Cloud:
Можно посмотреть, какие сети и scheme он поддерживает:
Возвращаемые kinds перечисляют сети и scheme, поддерживаемые Facilitator. При фактическом вызове всё равно следует ориентироваться на accepts, возвращаемые API. Вывод Facilitator /supported:
Результат означает:
  • /supported указывает, что Facilitator обладает возможностями проверки и расчёта для этих сетей и scheme.
  • Base и Solana обе поддерживают exact; upto в настоящее время предоставляется только в Base.
  • Разрешает ли конкретный API определённую сеть, всё равно определяется его 402 accepts.