Перейти к основному содержанию
Помимо прямой оплаты по API-запросам, Ace Data Cloud также поддерживает оплату заказов в консоли через X402. Основной протокол оплаты заказов и API-вызовов одинаков: первый запрос возвращает 402, клиент подписывает PAYMENT-SIGNATURE, затем повторяет тот же запрос. Разница в том, что оплата заказов относится к API платформы и требует токена аккаунта; тогда как AI API, вызываемый напрямую через x402.acedata.cloud, может использовать только X402 и не требует API Token.

Подготовка заказа

Перейдите в консоль Ace Data Cloud, выберите заказ, который необходимо оплатить, и запишите ID заказа. Если у вас ещё нет заказа, вы можете создать неоплаченный заказ на странице тарифов. Цена заказа определяется отображением на странице, а amount в ответе X402 402 является окончательным основанием для подписи.

Создание токена аккаунта

Запросы на оплату заказов требуют токена аккаунта. Откройте страницу Platform Token, создайте token в формате platform-v1-.... В последующих запросах используйте:
Токен аккаунта отличается от обычного API Token. Обычный API Token используется для потребления API-кредитов; токен аккаунта используется для операций с ресурсами платформы от имени вашего аккаунта, например для оплаты заказов.

Вызов 402

Сначала отправьте один запрос без PAYMENT-SIGNATURE:
Статус ответа будет 402, а ответ содержит accepts:
Для оплаты заказов используется официальный x402 v2: x402Version равен 2, network использует идентификатор CAIP-2, а поле суммы — amount. Результат выполнения программы при создании заказа на 10 Credits и вызове 402:
Следующие записи транзакций являются историческими фактическими образцами при старой политике, суммы и хеши транзакций сохранены без изменений. Для новых заказов X402 скидка за способ оплаты больше не применяется; используйте amount из текущего ответа 402 как основание для подписи и оплаты.
Пояснение результатов:
  • После успешного создания заказа его статус — Pending, в этот момент ещё нет оплаты в блокчейне.
  • Первый запрос pay/ не содержит PAYMENT-SIGNATURE, поэтому возвращается HTTP 402.
  • accepts одновременно предоставляет Base exact и Solana exact; в дальнейшем в этом руководстве выбирается Base.
  • Цена при создании заказа составляет 1.26; при оплате в период действия старой политики скидок X402 фактическая сумма подписи и расчёта составляет 1.2 USDC, что соответствует 1200000 atomic USDC.
Обратите внимание, что resource — это поле, возвращаемое сервером и участвующее в подписи; клиент не должен самостоятельно изменять протокол, путь или ID заказа в нём.

Подпись и повторная попытка

Для оплаты заказа можно повторно использовать низкоуровневые функции подписи из @acedatacloud/x402-client или acedatacloud-x402. Ниже приведён пример TypeScript:
Результат выполнения программы после подписи и повторной попытки того же заказа с Base exact:
Результат подтверждения в блокчейне:
Пояснение результатов:
  • status 200 означает, что интерфейс оплаты заказа платформы принял эту PAYMENT-SIGNATURE.
  • has_x_payment_response True означает, что заголовок ответа содержит закодированную в Base64 квитанцию PAYMENT-RESPONSE.
  • settle_header.success=True и network=base означают, что Facilitator завершил settlement в Base.
  • Итоговый статус заказа — Finished, pay_way — X402, pay_id содержит хеш транзакции в блокчейне.
  • Событие Transfer в BaseScan показывает, что адрес плательщика перевёл 1200000 atomic USDC на адрес получения платежей платформы, то есть 1.2 USDC.

Успешный ответ и квитанция

После успешной оплаты заказа тело ответа содержит информацию о заказе. Платформа также передаёт в заголовке ответа PAYMENT-RESPONSE закодированный в Base64 settlement response, который после декодирования обычно включает следующие поля: Если вам требуется сверка, рекомендуется одновременно сохранять ID заказа, адрес кошелька плательщика, transaction и итоговый статус заказа.

Примечания

  • Для оплаты заказа требуется токен учётной записи платформы, нельзя завершить её, используя только подпись X402-кошелька.
  • amount использует USDC atomic units, 1200000 означает 1.2 USDC.
  • Не формируйте адрес получения платежа или адрес актива самостоятельно, ориентируйтесь на accepts в ответе 402.
  • Если одна и та же PAYMENT-SIGNATURE отправляется повторно, Facilitator применяет защиту от повторного воспроизведения по nonce.

Ответ при неудачной оплате

Первый HTTP 402 без PAYMENT-SIGNATURE является нормальным платёжным вызовом и не означает неудачу оплаты. При сбое проверки или settlement после подписи стандартная строка error всё ещё сохраняется как совместимый резервный вариант, а стабильная структура ошибки возвращается в extensions.acedatacloud.paymentError:
Клиент должен в первую очередь локализовать по code, а для неизвестных code использовать общее сообщение о неудаче оплаты. charged — трёхсоставное поле: false возвращается только при явном отклонении до settlement; отсутствие поля означает, что статус списания неизвестен, и не может интерпретироваться как «средства не списаны». После перехода текущего заказа в Failed повторить оплату того же заказа нельзя; исправьте проблему с кошельком и создайте новый заказ. metadata.x402.last_error и metadata.x402.errors в списке и деталях заказов сохраняют тот же набор code, stage, retryable, charged и params; публичный пояснительный текст сохраняется в reason, а время возникновения — в timestamp. Например, insufficient_token_balance означает недостаточный баланс USDC в выбранной сети, а invalid_signature означает недействительную платёжную подпись; повторное чтение заказа не изменит их на универсальный payment_failed. Не записывайте и не отправляйте полную PAYMENT-SIGNATURE, подпись кошелька, payload авторизации, исходную диагностику Facilitator или RPC-ответы. Для проверки службе поддержки достаточно ID заказа и публичного code ошибки.

Выкуп и сжигание ACE для платежей Base и Solana

После включения стратегии выкупа 3% от фактически полученных соответствующих требованиям Circle USDC в основной сети Base и USDC в основной сети Solana используются для покупки и сжигания ACE без дополнительного списания средств с кошелька плательщика. Начисление происходит один раз при пополнении, а при последующем использовании этих Credits для вызова API повторного начисления не происходит; к историческим заказам со скидкой и заказам со старой стратегией начисление задним числом автоматически не применяется. Платежи Base сохраняют квитанцию о платеже в сети Base, а покупка и сжигание ACE выполняются асинхронно в Solana. Для соответствующих требованиям платежей точно начисляется 3% от фактически полученной суммы, без фиксированного лимита суммы выкупа на одну транзакцию или в день; доступные средства, рыночные котировки и подтверждения в блокчейне всё ещё могут влиять на время завершения. Объект ace_burn в деталях заказа предоставляет settlement_network, settlement_transaction и execution_network, а после завершения — swap_signature и burn_signature. Pending или Processing не означает, что сжигание уже выполнено; только Completed означает, что окончательное доказательство в блокчейне проверено. Если платёж Base ещё не достиг окончательного подтверждения, выкуп ожидает подтверждения, но это не влияет на уже зачисленные Credits.