API для пополнения баланса кредитных карт Agent Stripe

Авторизоваться Зарегистрироваться ✨ AI Агенты

Введение

API Agent Stripe Credit Top-Up позволяет ИИ-агенту проверять баланс кредитов на счете и, в пределах установленных пользователем лимитов, списывать средства с сохраненного способа оплаты Stripe для пополнения счета.

Данный API не является x402. Для этого требуется существующая учетная запись BuiltWith и отдельно настроенный ключ выставления счетов агента. Для безучетных платежей Base USDC используйте BuiltWith x402 payments page.

Все три основные точки доступа размещены на payments.builtwith.com.

Прежде чем агент сможет использовать эти конечные точки, пользователь должен включить выставление счетов через API агента и настроить лимиты расходов. https://payments.builtwith.com/agent-payment-api-config.

После ручной активации агенты могут использовать устаревшие псевдонимы путей mppx для тех же операций пополнения счета Stripe. https://api.builtwith.com/mppx. Эти псевдонимы не являются протоколом x402 или протоколом проверки платежей.

Аутентификация

Скопируйте отдельно заданный ключ выставления счетов агента со страницы конфигурации выставления счетов и отправьте его в заголовке Authorization. Общие ключи API BuiltWith и временные токены устройств bw- не позволяют приобретать кредиты.

Authorization: Bearer YOUR_AGENT_BILLING_KEY

Устаревший параметр запроса KEY устарел, поскольку учетные данные в URL-адресах могут сохраняться в журналах и истории браузера.

Запросы с отсутствующим, недействительным или отключенным ключом возвращают HTTP 401. Учетные записи с приостановленной оплатой возвращают HTTP 403.

🤖 Подсказка от ИИ-агента

Reference https://api.builtwith.com/llms.txt and
https://raw.githubusercontent.com/builtwith/builtwith-ai-sdk/refs/heads/main/README.md
Add BuiltWith Agent Stripe Credit Top-Up API support to my app. This is saved-card
account billing, not x402. Check the account API-credit balance and, if below 1000,
purchase 2000 more using a unique Idempotency-Key and the scoped Agent Billing Key.
If the legacy mppx path aliases are desired, use
https://api.builtwith.com/mppx/openapi.json and the Agent Payment API routes
https://api.builtwith.com/mppx/api-discovery,
https://api.builtwith.com/mppx/api-configuration, and
https://api.builtwith.com/mppx/api-purchase.

mppx Stripe Credit Top-Up Path Aliases

Эти устаревшие пути mppx являются прокси для API пополнения баланса Stripe с помощью сохраненного метода. Они не поддерживают код ошибки x402 и не возвращают и не принимают заголовки payment-challenge.

Открытие

GET https://api.builtwith.com/mppx/openapi.json

Маршруты

GET https://api.builtwith.com/mppx/api-discovery

GET https://api.builtwith.com/mppx/api-configuration

POST https://api.builtwith.com/mppx/api-purchase

{ "credits": 2000 }

Отправьте ключ выставления счетов агента в поле «Авторизация: Bearer» и укажите уникальный ключ идемпотентности при совершении покупок.

GET /v1/billing/api-discovery — Кредитовый баланс

Возвращает текущий баланс средств API на счете.

Запрос

GET https://payments.builtwith.com/v1/billing/api-discovery
Authorization: Bearer YOUR_AGENT_BILLING_KEY

Поля ответа

Поле	Тип	Описание
`credits_total`	`number`	Общая сумма средств, когда-либо зачисленных на счет.
`credits_used`	`number`	Кредиты, израсходованные на вызовы API на данный момент.
`credits_available`	`number`	Остаток доступных кредитов (общая сумма минус использованные). Это то, что агент должен проверить перед выполнением вызовов API.

Пример ответа

{
  "credits_total": 10000,
  "credits_used": 1234,
  "credits_available": 8766
}

GET /v1/billing/api-configuration — Лимиты расходов

Возвращает установленные лимиты расходов и сумму уже использованного ежемесячного лимита. Агент должен проверить это перед попыткой покупки, чтобы избежать отклоненных запросов.

Запрос

GET https://payments.builtwith.com/v1/billing/api-configuration
Authorization: Bearer YOUR_AGENT_BILLING_KEY

Поля ответа

Поле	Тип	Описание
`max_per_purchase`	`number`	Максимальное количество кредитов, которое агент может приобрести за одну транзакцию.
`max_monthly`	`number`	Максимальное количество кредитов, которое агент может приобрести в течение текущего календарного месяца по UTC.
`monthly_purchased`	`number`	Кредиты, уже приобретенные агентом в этом календарном месяце.
`monthly_remaining`	`number`	Сколько ещё кредитов можно приобрести в этом месяце, прежде чем будет достигнут месячный лимит?
`cost_per_2000_credits_usd`	`number`	Стоимость покупки на сумму не менее 2000 кредитов в долларах США. Используйте эту информацию для оценки стоимости планируемой покупки.

Пример ответа

{
  "max_per_purchase": 5000,
  "max_monthly": 20000,
  "monthly_purchased": 5000,
  "monthly_remaining": 15000,
  "cost_per_2000_credits_usd": 99.00
}

POST /v1/billing/api-purchase — Купить кредиты

Списание средств с сохраненного пользователем способа оплаты Stripe и немедленное зачисление на счет. Покупка осуществляется в соответствии с лимитами на одну покупку и на месяц, установленными в настройках выставления счетов Agent API.

Запрос

POST https://payments.builtwith.com/v1/billing/api-purchase

Отправьте ключ выставления счетов агента в указанном диапазоне в качестве Authorization: Bearer YOUR_AGENT_BILLING_KEY, и отправить уникальный Idempotency-Key. Используйте этот ключ повторно только при повторной попытке совершить ту же самую покупку.

Текст запроса

Поле	Тип	Необходимый	Описание
`credits`	`number`	Да	Количество кредитов для покупки должно быть фиксированным и составлять 2000 единиц. Не должно превышать `max_per_purchase` или оставшуюся часть ежемесячного пособия.

Успешный ответ (HTTP 200)

Поле	Тип	Описание
`success`	`boolean`	`true`
`credits_purchased`	`number`	Кредиты зачислены на счет.
`cost_usd`	`number`	Сумма к оплате указана в долларах США.
`payment_id`	`string`	Идентификатор платежного намерения Stripe для сверки.
`credits_available`	`number`	Обновление доступного кредитного баланса после покупки.

Пример запроса

Authorization: Bearer YOUR_AGENT_BILLING_KEY
Idempotency-Key: 72b7b97c-3b6d-4c64-9bbf-20fd2a931514
Content-Type: application/json

{ "credits": 2000 }

Пример успешного ответа

{
  "success": true,
  "credits_purchased": 2000,
  "cost_usd": 99.00,
  "payment_id": "pi_3abc123xyz",
  "credits_available": 10766
}

Ответы об ошибках

HTTP	Значение
400	Ошибка проверки — отсутствует ключ идемпотентности, количество кредитов не превышает 2000, превышен лимит на одну покупку или превышен ежемесячный лимит UTC.
401	Отсутствует или недействителен ключ выставления счетов агенту. Содержит запрос WWW-Authenticate.
402	Платеж через Stripe не удался или в системе не указан способ оплаты, за который можно произвести оплату.
403	Вместо ограниченного по области действия ключа API был предоставлен общий ключ API, в противном случае выставление счетов по учетной записи приостанавливается.
409	Ключ идемпотентности все еще находится в процессе разработки или ранее использовался с другим входным сигналом.
405	Метод недопустим — конечная точка требует POST-запроса.

Специальные домены

Мы ведём два списка, которые пригодятся вам при поиске доменов: списки игнорирования и списки BuiltWith Suffix.

Список игнорирования
TЭто наш внутренний список доменов, которые мы не индексируем. Они либо заблокированы, либо содержат слишком много вводящих в заблуждение технологий, либо слишком много поддоменов с пользовательским контентом.

BuiltWith Список суффиксов
Это основано на Список публичных суффиксов но включает множество дополнительных записей для компаний с поддоменами, которые следует считать доменами верхнего уровня. Этот список обеспечивает лучшую видимость внутренних веб-сайтов, например, он выводит northernbeaches.nsw.gov.au на верхний уровень по сравнению с nsw.gov.au.

Игнорировать домены (XML, JSON or TXT)

https://api.builtwith.com/ignoresv1/api.json

Суффиксные домены (XML, JSON or TXT)

https://api.builtwith.com/suffixv1/api.json

Коды ошибок

Обратите внимание, что отправка сообщений об ошибках в этом формате не может быть гарантирована, ваша реализация должна также рассматривать коды ответа, отличные от 200, как ошибки. Свойство Lookup будет иметь значение null (json) или не будет предоставлено (xml), если ошибка связана с сервером. Просмотреть все возможные правильно сформированные коды ошибок.

Условия эксплуатации

Наш стандартные условия распространяется на использование всех наших API.

В целом, вы можете использовать API для улучшения своего продукта различными способами. Единственное ограничение — вы не можете перепродавать данные в их исходном виде или предоставлять дублирующий функционал builtwith.com и связанным с ним сервисам.