402 Payment Required. Благодаря возможностям X402 от Ace Data Cloud вызывающая сторона может не создавать API Token, не пополнять баланс аккаунта заранее, а напрямую оплачивать USDC в сети при каждом API-запросе.
Этот набор документов организован в порядке реального подключения: сначала выполните один минимальный запрос, затем подключите SDK, после этого изучите сети, тарифные схемы, оплату заказов и Facilitator. Рекомендуется читать сверху вниз согласно таблице ниже.
Рекомендуемый путь подключения
Если вы хотите только вызывать Ace Data Cloud API, в первую очередь используйте официальный SDK:- TypeScript:
@acedatacloud/sdk+@acedatacloud/x402-client - Python:
acedatacloud+acedatacloud-x402
SDK автоматически выполнит шаги первого запроса без аутентификации, разбора
402 Payment Required, вызова payment handler и повторной попытки с PAYMENT-SIGNATURE. Вам нужно лишь подготовить кошелек с USDC и выбрать сеть, которую вы хотите использовать.
Если вы хотите, чтобы ваш собственный API также поддерживал прием платежей X402, вам необходимо прочитать документацию Facilitator и понять взаимосвязь между paymentRequirements, paymentPayload, /verify и /settle.
Статус поддержки
Ace Data Cloud X402 прошел проверку на публичном API, официальных SDK, Facilitator и пути ончейн-расчетов. В таблице ниже приведен текущий статус по наиболее часто используемым возможностям при подключении разработчиков.
Следующий вывод используется только для демонстрации формата ответов проверенных путей. При фактическом подключении всегда ориентируйтесь на
accepts, возвращаемый текущим API.
- Пакеты npm и PyPI были установлены и успешно импортированы в чистом окружении.
- Неоплаченный API-запрос возвращает 402, а
acceptsсодержит доступные способы оплаты для Base и Solana. accepts[].networkявляется идентификатором CAIP-2; при выборе сети клиент должен сопоставлять строку CAIP-2.- TypeScript SDK и Python SDK оба могут автоматически обработать 402 и выполнить платный повторный запрос.
- Base
exact, Baseuptoи оплата заказа имеют публично доступные адреса explorer. - Подписанный потолок Base
uptoсоставляет95215atomic USDC, фактический settlement составляет3atomic USDC, что демонстрирует особенность постоплатного измерения с расчётом по фактическому использованию. - Для Solana
exactпроверены HTTP 402 -> HTTP 200 и вывод модели. Поскольку запросы к публичному RPC могут ограничиваться по частоте, для строгой сверки рекомендуется использовать собственный Solana RPC или записи о settlement со стороны платформы для подтверждения подписи транзакции.
Примечания по интеграции
При интеграции разработчикам следует в первую очередь обращать внимание на требования к оплате в реальном времени, возвращаемые текущим запросом, а не копировать примерные суммы или адреса из документации:accepts[].maxAmountRequired— максимальная сумма, которая может быть подписана для текущего запроса.accepts[].asset— контракт USDC или mint, который должен использоваться для этого запроса.accepts[].extra.chainId、accepts[].extra.facilitatorAddressиaccepts[].extra.verifyingContractучаствуют в подписи EVM typed data.- Для
uptoкошелёк должен сначала авторизовать Permit2 для USDC целевой сети; при отсутствии авторизации будет возвращёнPERMIT2_ALLOWANCE_REQUIRED. - Если явно требуется использовать постоплатное измерение, передайте
preferScheme: 'upto'в TypeScript SDK; в противном случае SDK выберет первое доступное requirement, возвращённое сервером для этой сети.
Диапазон, который можно публично проверить
Перед интеграцией можно сначала проверить эти публичные точки входа и поведение SDK:- API-запрос без
AuthorizationилиPAYMENT-SIGNATUREвернёт402 Payment Required;acceptsв ответе является единственным основанием для подписи данного запроса. - TypeScript SDK и Python SDK оба предоставляют payment handler; транспортный слой SDK после получения 402 вызовет handler и повторит запрос один раз.
https://facilitator.acedata.cloud/.well-known/x402:возвращает сети, scheme и протокольные конечные точки, поддерживаемые Facilitator; цена API по-прежнему определяется 402, возвращаемым целевым запросом в реальном времени.https://facilitator.acedata.cloud/supported:возвращает сети и scheme, поддерживаемые Facilitator.- Репозиторий X402Client содержит расширенные инструменты ончейн-проверки, которые могут использоваться для подтверждения подписи, повторной попытки и поведения settlement; вывод инструментов не заменяет
accepts, возвращаемый онлайн API.
upto относится к постоплатному измерительному settlement и подходит для API, таких как чат-дополнения и вызовы моделей, где фактическое использование становится известно только после ответа. В настоящее время только Base предоставляет upto; если проверка подписи не удалась, проверьте, соответствуют ли chain id, адрес facilitator, spender, контракт USDC и Permit2 allowance ответу 402.
