Перейти к основному содержанию
Facilitator — это серверный компонент расчётов в цепочке X402. Клиент отвечает за подпись, а Gateway или ваш сервер отвечает за вызов /verify и /settle Facilitator. Адрес production Facilitator Ace Data Cloud:
Репозиторий исходного кода: https://github.com/AceDataCloud/FacilitatorX402

Соглашения wire v2

Цепочка X402 Ace Data Cloud полностью использует официальный x402 v2 и больше не принимает заголовок запроса X-Payment v1. При интеграции необходимо обратить внимание на три пункта:
  • Заголовок запроса — PAYMENT-SIGNATURE, его значением является JSON envelope в кодировке base64.
  • Верхний уровень envelope должен содержать x402Version: 2 и объявлять выбранные для этого раза scheme и network с помощью объекта accepted.
  • network использует идентификатор CAIP-2 (например, eip155:8453), нельзя указывать сокращения вроде base.
Структура envelope:
Ответ 402, помимо JSON body, также содержит заголовок ответа PAYMENT-REQUIRED, значением которого является содержимое того же challenge в кодировке base64, что позволяет клиенту читать требования к оплате без разбора body.

Основные интерфейсы

GET /supported

Просмотр поддерживаемых сетей и scheme:
Пример ответа:
Описание результата:
  • network использует идентификатор CAIP-2, а не сокращения вроде base или solana.
  • /supported означает, что Facilitator обладает соответствующими возможностями верификации и расчётов.
  • Base и Solana поддерживают exact; upto в настоящее время предоставляется только на Base.
  • signers — это адреса, которые Facilitator использует для отправки транзакций расчёта.
  • Разрешает ли конкретный API эти опции, по-прежнему определяется его accepts в ответе 402.

POST /verify

Проверяет, соответствует ли переданный клиентом PAYMENT-SIGNATURE определённому payment requirement. Тело запроса:
Поля paymentRequirements в v2: scheme, network, asset, amount, payTo, maxTimeoutSeconds и extra; полем суммы является amount. В accepts[] ответа API 402 также дополнительно возвращается maxAmountRequired, чтобы клиент мог прочитать верхний лимит, однако оно не относится к полям тела запроса Facilitator. Успешный ответ:
После декодирования заголовок ответа PAYMENT-RESPONSE оплаты production-заказа содержит результат settlement. Результат выполнения программы оплаты заказа Base:
Описание результата:
  • success=True означает, что settlement Facilitator выполнен успешно.
  • transaction — это хеш ончейн-транзакции, в pay_id заказа также записывается то же значение.
  • В explorer можно увидеть перевод 1200000 atomic USDC Base.
  • errorReason=None означает, что этот settlement не вернул бизнес-ошибку.
Ошибка верификации также обычно возвращает HTTP 200, но isValid имеет значение false. Бизнес-сторона должна читать invalidReason, а не смотреть только на код состояния HTTP.

POST /settle

Рассчитывает в сети уже проверенное разрешение. Тело запроса в целом идентично /verify. Отличие upto состоит в следующем: paymentRequirements.amount при settle переписывается на фактическую сумму расчёта; верхний лимит подписи записывается Facilitator на этапе verify, а при settle проверяется, что фактическая сумма не превышает этот лимит. Успешный ответ:
Если фактическая сумма upto равна 0, transaction может быть пустой строкой, что означает отсутствие необходимости отправлять ончейн-транзакцию.

Как Ace Data Cloud Gateway использует Facilitator

Цепочка API Gateway Ace Data Cloud выглядит следующим образом:
  1. Клиент впервые запрашивает API без Authorization и PAYMENT-SIGNATURE.
  2. Gateway рассчитывает предполагаемую цену запроса, возвращая 402 и accepts.
  3. После подписи клиент повторяет запрос с PAYMENT-SIGNATURE.
  4. Gateway декодирует PAYMENT-SIGNATURE и выбирает соответствующий payment requirement.
  5. Gateway вызывает Facilitator /verify.
  6. После успешного /verify Gateway пропускает запрос к целевому API.
  7. После ответа целевого API Gateway вызывает Facilitator /settle на этапе /record.
  8. Gateway записывает хеш ончейн-транзакции в metadata записи использования.
exact рассчитывает подписанную сумму на шаге 7; upto записывает amount согласно фактическому использованию на шаге 7, затем рассчитывает фактическую сумму.

Как интегрировать собственный API

Если вы хотите, чтобы ваш собственный API поддерживал X402, можно реализовать его согласно этой структуре:
  1. Подготовьте paymentRequirements для каждого платного интерфейса, включая сеть, сумму, адрес получателя, адрес актива и signature domain.
  2. Если запрос не содержит PAYMENT-SIGNATURE, верните HTTP 402 и accepts.
  3. Если запрос содержит PAYMENT-SIGNATURE, выполните Base64-декодирование для получения paymentPayload.
  4. Вызовите Facilitator /verify.
  5. После успешной проверки выполните бизнес-логику.
  6. После успешного выполнения бизнес-логики вызовите Facilitator /settle.
  7. Сохраните payer, transaction, amount, network для сверки.
Сервер должен использовать собственные сгенерированные paymentRequirements для вызова /verify и /settle, не доверяйте сумме, адресу получателя или адресу актива, переданным обратно клиентом.

Защита от повторного воспроизведения

Facilitator записывает nonce. Авторизацию с одинаковым nonce нельзя повторно проверять и проводить расчёт. Это означает:
  • Клиент должен подписывать новый envelope для каждого запроса;
  • Если /settle уже отправил транзакцию, но подтверждение временно отсутствует, можно повторить /settle с тем же nonce для идемпотентной сверки;
  • Не кэшируйте один и тот же PAYMENT-SIGNATURE для использования в нескольких API-вызовах.

Распространённые ошибки