Разработчикам

Подключите AI-агента за пару минут

Agentpay считает стоимость работы вашего агента и списывает с баланса клиента. Подключение — это один POST-запрос на каждое событие агента.

1. Создайте API-ключ

В кабинете → API-ключи → «Создать ключ». Ключ показывается один раз — сохраните его. Передавайте его в заголовке Authorization: Bearer ….

Открыть API-ключи

2. Отправьте первое событие

Каждый раз, когда агент выполнил работу, отправьте событие. Примеры — cURL, TypeScript SDK и обычный fetch:

POSThttps://agent-pay.lamagate.com/api/v1/events

curl -X POST https://agent-pay.lamagate.com/api/v1/events \
  -H "Authorization: Bearer $AGENT_BILLING_API_KEY" \
  -H "Idempotency-Key: evt_$(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_id": "agent_123",
    "event_name": "support_ticket_resolved",
    "units": 1,
    "success": true,
    "input_tokens": 1200,
    "output_tokens": 500,
    "duration_ms": 18000,
    "payload": { "ticket_id": "123" }
  }'

Успешный ответ

200 OK

{
  "accepted": true,
  "idempotent_replay": false,
  "usage_event_id": "clx...",
  "cost": { "amount": 35, "currency": "RUB", "minor_units": 3500 },
  "balance_after": { "amount": 4965, "currency": "RUB", "minor_units": 496500 }
}

Если баланс закончился

insufficient_balance

// HTTP 402 Payment Required
{
  "error": {
    "code": "insufficient_balance",
    "message": "Недостаточно средств на балансе"
  }
}

Idempotency-Key делает повторы безопасными: событие с тем же ключом не списывает деньги второй раз — мы возвращаем исходный результат с idempotent_replay: true. Используйте уникальный ID операции вашего агента.

3. Как считается стоимость

Для агента задаётся тариф. Стоимость события считается по типу метрики:

`per_run` За запуск	Фиксированная цена за каждое событие
`per_successful_run` За успешный результат	Списывается только при success = true
`per_message` За сообщение	Цена × units
`per_1000_tokens` За 1000 токенов	ceil((input + output) / 1000) × цена
`per_minute` За минуту работы	ceil(duration_ms / 60000) × цена
`custom_event` Произвольное событие	Цена × units, матчинг по event_name

4. Idempotency-Key

Передавайте уникальный Idempotency-Key на каждое событие (например, ID операции вашего агента). Повтор с тем же ключом не спишет деньги второй раз — вернётся исходный результат с idempotent_replay: true. Это делает ретраи при сетевых сбоях безопасными.

5. Проверка баланса

curl https://agent-pay.lamagate.com/api/v1/balance \
  -H "Authorization: Bearer $AGENT_BILLING_API_KEY"

# { "balance": { "amount": 4965, "currency": "RUB", "minor_units": 496500 } }

6. Какие ошибки бывают

invalid_api_keyКлюч неверный или отозван
insufficient_balanceНа балансе организации недостаточно средств
agent_pausedАгент на паузе — события не тарифицируются
validation_errorНекорректное тело запроса или нет Idempotency-Key
rate_limitedСлишком много запросов — снизьте частоту

Ошибки приходят в виде { "error": { "code", "message" } }.

7. TypeScript SDK

Пакет @agent-billing/sdk оборачивает API: track(), getBalance(), getUsage(). Пример — на вкладке «TypeScript SDK» выше. Idempotency-Key проставляется автоматически.

OpenAPI-документация

Если вы хотите быстро протестировать API или сгенерировать клиент под свой язык, используйте OpenAPI spec. Это дополнительный инструмент — пошаговый гайд выше остаётся основным способом подключения.

Open API Docs Download openapi.json

Готовы попробовать на живых данных?

Открыть демо-аккаунт