Обзор API

Базовый URL, аутентификация, соглашения и тур по эндпоинтам.

API AgentFlow — это JSON-over-HTTPS интерфейс на Hono. Используется веб-приложением, Telegram-ботом и интеграторами. SSE применяется там, где нужен реалтайм-стриминг.

​

Базовый URL

https://api.agentflow.website

Для self-hosted-деплоя замените на свой домен.

​

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

Большинство эндпоинтов требуют сессионную куку, выданную SIWE или Telegram-логином.

SIWE

1. POST /auth/nonce — получить nonce.
2. Подписать SIWE-сообщение в кошельке пользователя.
3. POST /auth/verify — отправить подпись; получить JWT-куку af_session.

Telegram

1. Пользователь жмёт /start у @AIAgentFlow_bot.
2. Бот вызывает POST /auth/telegram с подписанным payload.
3. Сервер выдаёт куку af_session.

API Key

1. Создайте ключ в кабинете или через POST /me/api-keys.
2. Отправляйте его как x-api-key: af_live_... в каждом запросе — cookie не нужна. Полный жизненный цикл — API-ключи.

Service-to-service

Внутренние эндпоинты под /internal/* принимают шейред-сикрет в хедере X-Internal-Token. Эти эндпоинты не для публичных интеграторов.

Кука HttpOnly, Secure, SameSite=Lax, lifetime 30 дней. Отправляйте в каждом запросе.

См. Auth — там полные схемы request/response.

​

Группы эндпоинтов

Auth

SIWE, Telegram-логин, logout.

API-ключи

Долгоживущие bearer-токены для server-to-server вызовов.

Marketplace

Список, fetch, публикация агентов. Цены инструментов.

Tokens

Off-chain метаданные для токенов, запущенных через factory.launch. Держатели и сделки из чейн-индексера.

Projects

Attach, start, stream, subscribe.

FLOW Onchain

Агрегированные ончейн-чтения для $FLOW, GWT, дневного лимита, лимита дохода и состояния дерева caller.

Subscriptions

Plus / Pro / Max — feature gates для маркетплейса и live-сборки.

Webhooks

Inbound-коллбэки провайдеров. HMAC-проверка.

​

Соглашения

• Content-Type: всегда application/json. Multipart используется только в нескольких эндпоинтах загрузки файлов (документировано inline).
• Errors: 4xx и 5xx возвращают { "error": { "code": "...", "message": "..." } }. Коды стабильны и перечислены по эндпоинтам.
• Pagination: list-эндпоинты принимают ?cursor= и возвращают nextCursor. Размер страницы по умолчанию 20, max 100.
• Idempotency: write-эндпоинты принимают опциональный хедер Idempotency-Key. Повторные запросы с тем же ключом возвращают исходный результат без побочных эффектов.

​

Rate limits

Bucket	Limit
Anonymous	30 req / min / IP
Authenticated	240 req / min / user
Internal	1000 req / min / token

Превышение лимита возвращает 429 с хедером Retry-After.

​

SSE-эндпоинты

Streaming-эндпоинты (стрим проекта, тики цены токена) используют text/event-stream. Реконнект обрабатывается стандартным API EventSource; сервер уважает Last-Event-ID для replay.