/verify и /settle Facilitator.
Адрес production Facilitator Ace Data Cloud:
Соглашения 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.
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 можно увидеть перевод
1200000atomic USDC Base. errorReason=Noneозначает, что этот settlement не вернул бизнес-ошибку.
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 выглядит следующим образом:- Клиент впервые запрашивает API без
AuthorizationиPAYMENT-SIGNATURE. - Gateway рассчитывает предполагаемую цену запроса, возвращая 402 и
accepts. - После подписи клиент повторяет запрос с
PAYMENT-SIGNATURE. - Gateway декодирует
PAYMENT-SIGNATUREи выбирает соответствующий payment requirement. - Gateway вызывает Facilitator
/verify. - После успешного
/verifyGateway пропускает запрос к целевому API. - После ответа целевого API Gateway вызывает Facilitator
/settleна этапе/record. - Gateway записывает хеш ончейн-транзакции в metadata записи использования.
exact рассчитывает подписанную сумму на шаге 7; upto записывает amount согласно фактическому использованию на шаге 7, затем рассчитывает фактическую сумму.
Как интегрировать собственный API
Если вы хотите, чтобы ваш собственный API поддерживал X402, можно реализовать его согласно этой структуре:- Подготовьте
paymentRequirementsдля каждого платного интерфейса, включая сеть, сумму, адрес получателя, адрес актива и signature domain. - Если запрос не содержит
PAYMENT-SIGNATURE, верните HTTP 402 иaccepts. - Если запрос содержит
PAYMENT-SIGNATURE, выполните Base64-декодирование для полученияpaymentPayload. - Вызовите Facilitator
/verify. - После успешной проверки выполните бизнес-логику.
- После успешного выполнения бизнес-логики вызовите Facilitator
/settle. - Сохраните
payer,transaction,amount,networkдля сверки.
paymentRequirements для вызова /verify и /settle, не доверяйте сумме, адресу получателя или адресу актива, переданным обратно клиентом.
Защита от повторного воспроизведения
Facilitator записывает nonce. Авторизацию с одинаковым nonce нельзя повторно проверять и проводить расчёт. Это означает:- Клиент должен подписывать новый envelope для каждого запроса;
- Если
/settleуже отправил транзакцию, но подтверждение временно отсутствует, можно повторить/settleс тем же nonce для идемпотентной сверки; - Не кэшируйте один и тот же
PAYMENT-SIGNATUREдля использования в нескольких API-вызовах.

