API Overview

Base URL, authentication, conventions, and a tour of the endpoints.

The AgentFlow API is a JSON-over-HTTPS interface built on Hono. It is consumed by the web app, the Telegram bot, and integrators. SSE is used where real-time streaming is required.

Base URL

https://api.agentflow.website

For self-hosted deployments, replace with your own domain.

Authentication

Most endpoints require a session cookie issued by SIWE or Telegram login.

SIWE

1. POST /auth/nonce — get a nonce.
2. Sign the SIWE message in the user’s wallet.
3. POST /auth/verify — submit the signature; receive a JWT cookie af_session.

Telegram

1. User taps /start on @AIAgentFlow_bot.
2. Bot calls POST /auth/telegram with signed payload.
3. Server issues af_session cookie.

API Key

1. Create a key in the cabinet or via POST /me/api-keys.
2. Send it as x-api-key: af_live_... on every request — no cookie needed. See API Keys for the full lifecycle.

Service-to-service

Internal endpoints under /internal/* accept a shared secret header X-Internal-Token. These endpoints are not for public integrators.

The cookie is HttpOnly, Secure, SameSite=Lax, lifetime 30 days. Send it on every request.

See Auth for the full request/response schemas.

Endpoint groups

Auth

SIWE, Telegram login, logout.

API Keys

Long-lived bearer tokens for server-to-server calls.

Marketplace

List, fetch, publish agents. Tool prices.

Tokens

Off-chain metadata for tokens launched via factory.launch. Holders and trades from the chain indexer.

Projects

Attach, start, stream, subscribe.

FLOW Onchain

Aggregate on-chain reads for the caller’s $FLOW, GWT, daily limit, income limit, tree state.

Subscriptions

Plus / Pro / Max — feature gates for marketplace + live build.

Webhooks

Inbound provider callbacks. HMAC verification.

Conventions

• Content-Type: always application/json. Multipart is used only on a few file-upload endpoints (documented inline).
• Errors: 4xx and 5xx return { "error": { "code": "...", "message": "..." } }. Codes are stable and listed per endpoint.
• Pagination: list endpoints accept ?cursor= and return nextCursor. Page size is 20 by default, max 100.
• Idempotency: write endpoints accept an optional Idempotency-Key header. Repeated requests with the same key return the original result without side effects.

Rate limits

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

Exceeded limits return 429 with a Retry-After header.

SSE endpoints

Streaming endpoints (project stream, token price ticks) use text/event-stream. Reconnection is handled by the standard EventSource API; the server honors Last-Event-ID for replay.