Оплата API в USDC: как через X402 и кошелёк экономить 5% на каждом запросе к Ace Data Cloud

Разработчики, работающие с несколькими моделями (GPT, Claude, Gemini, Midjourney, Suno, Flux и другими) через единый API, рано или поздно упираются в вопрос расчётов: банковская карта, комиссии эквайринга, задержки конвертации. Ace Data Cloud поддерживает альтернативный способ оплаты заказов — расчёт в USDC по протоколу X402, с ончейн-подтверждением в сетях Solana и Base. В этой статье разберём, как это устроено технически и как получить скидку 5% при оплате в USDC.

Что такое X402 и зачем он нужен

X402 — это протокол ончейн-оплаты, построенный поверх HTTP-статуса 402 Payment Required. Когда клиент обращается к API без токена оплаты, сервер возвращает 402 и объект accepts с параметрами, необходимыми для подписи транзакции: сумму, адрес актива USDC, идентификатор сети (в формате CAIP-2) и данные фасилитатора. После подписи клиент повторяет запрос с заголовком PAYMENT-SIGNATURE, и сервер выполняет верификацию и расчёт.

У X402 в Ace Data Cloud два независимых применения:

Оплата отдельных API-вызовов «по факту» без предварительного пополнения баланса — полезно для одноразовых интеграций или тестов.
Оплата заказов в консоли (покупка пакетов, пополнение баланса аккаунта) — именно этот сценарий даёт скидку 5% при оплате в USDC.

Классический сценарий: пополнение баланса и оплата в USDC

Базовая модель платформы — один endpoint, множество моделей, списание по факту использования с баланса. Пополнить баланс можно двумя способами: обычной картой (Stripe и другие способы) или через X402-транзакцию в USDC. При выборе оплаты в USDC заказ автоматически получает скидку 5% от номинала — так платформа стимулирует расчёты без международной банковской карты, что особенно удобно для разработчиков без доступа к карточным платёжным системам.

Порядок действий такой:

В консоли создаётся заказ на покупку пакета или пополнение баланса приложения.
Для заказа запрашивается платёжная сессия с методом X402.
Кошелёк с USDC подписывает транзакцию в выбранной сети — поддерживаются Solana и Base.
После подтверждения транзакции ончейн статус заказа переходит в Finished, а баланс приложения пополняется с учётом скидки.

Управлять заказами можно через раздел https://platform.acedata.cloud/console/coin, а сами приложения и токены — в https://platform.acedata.cloud/console/applications.

Минимальный запрос и структура accepts

Если запрос отправлен без оплаты, сервер вернёт 402 с телом, где перечислены доступные варианты расчёта. Пример через curl:

curl -i -X POST "https://api.acedata.cloud/mj/imagine" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "a cyberpunk city at night, ultra detailed"
  }'

В ответе HTTP 402 будет объект accepts, содержащий network (в формате CAIP-2, например eip155:8453 для Base или solana:5eykt4... для Solana), asset — адрес контракта или mint USDC, а также maxAmountRequired — максимальную сумму для подписи текущего запроса. Важно ориентироваться именно на значения из живого ответа API, а не копировать примеры из документации — суммы и адреса контрактов могут отличаться в зависимости от сети и типа биллинга.

exact и upto: два режима биллинга

В X402 предусмотрены две схемы:

exact — фиксированная сумма, известная заранее. Подходит для оплаты заказов в консоли и для API с постоянной ценой за вызов.
upto — расчёт по факту использования (post-measurement), когда итоговая стоимость известна только после ответа модели, например при чат-комплишенах с переменной длиной генерации. Подписывается верхняя граница (ceiling), а списывается фактическая сумма — это видно из типового расчёта: сигнатура на потолок в 95215 атомарных единиц USDC при фактическом списании 3 атомарных единиц.

На момент публикации upto поддерживается только в сети Base; для него необходимо, чтобы кошелёк заранее выдал разрешение Permit2 на токен USDC в этой сети — иначе API вернёт ошибку PERMIT2_ALLOWANCE_REQUIRED.

Пример на Python

Официальный Python SDK автоматически обрабатывает первый неоплаченный запрос, разбирает 402, вызывает платёжный обработчик и повторяет запрос с подписью:

import os
from acedatacloud import Client
from acedatacloud_x402 import X402PaymentHandler

client = Client(
    base_url="https://api.acedata.cloud",
    payment_handler=X402PaymentHandler(
        private_key=os.environ["WALLET_PRIVATE_KEY"],
        network="base",           # или "solana"
        prefer_scheme="upto",     # опционально, для post-measurement API
    ),
)

response = client.post(
    "/mj/imagine",
    json={"prompt": "a cyberpunk city at night, ultra detailed"},
)

print(response.status_code)
print(response.json())

SDK сам обработает переход от 402 к 200: получит accepts, соберёт и подпишет платёжную нагрузку, вложит заголовок PAYMENT-SIGNATURE и повторит вызов. Разработчику нужно только подготовить кошелёк с USDC на выбранной сети и указать приватный ключ через переменную окружения — никогда не храните ключи в коде.

Проверка публичных эндпоинтов перед интеграцией

Перед тем как встраивать X402 в продакшен, полезно свериться с двумя публичными точками:

https://x402.acedata.cloud/.well-known/x402 — документ обнаружения протокола со ссылками на спецификации.
https://facilitator.acedata.cloud/supported — список сетей и схем, поддерживаемых текущим фасилитатором.

Быстрая проверка curl-ом:

curl -sS "https://x402.acedata.cloud/.well-known/x402" | jq .
curl -sS "https://facilitator.acedata.cloud/supported" | jq .

Итог

Оплата в USDC через X402 закрывает сразу две задачи: разработчик получает предсказуемый ончейн-расчёт без международной банковской карты, а платформа даёт скидку 5% на заказы, оплаченные в USDC. Для разовых вызовов подходит прямой 402-флоу с подписью запроса, для регулярной работы удобнее один раз пополнить баланс через оплату заказа в консоли и дальше списывать средства по мере использования моделей — GPT, Claude, Gemini, Midjourney, Suno, Flux и десятков других — через единый endpoint https://api.acedata.cloud.

Подробности по интеграции, включая TypeScript и Python SDK, схемы exact/upto и работу с фасилитатором, смотрите в разделе документации: https://platform.acedata.cloud/documents. Общий обзор платформы и локализованная версия для русскоязычных разработчиков — на https://platform.acedata.cloud/ru.

Search This Blog

AceDataCloud