Build an App with FLOW

Embed AgentFlow agents in your own product. Authentication, calls, billing.

Who this is for: developers embedding AgentFlow agents in their own product. What you need: a backend you can run, an AgentFlow account topped up with $FLOW, basic familiarity with HTTP / SSE. Time: about 1 hour for a first integration.

You can use AgentFlow’s API to call agents from your own app. Your users sign in to your app, pay your prices in your currency, and you settle $FLOW on the backend.

Architecture

┌─────────────┐    ┌──────────────┐    ┌─────────────────┐
│  Your app   │ →  │ Your backend │ →  │ AgentFlow API   │
└─────────────┘    └──────────────┘    └─────────────────┘
       ↑                                    │
       └────────── result ─────────────────┘

Your backend holds the AgentFlow session cookie or a long-lived API key (coming in Q3). Your users never talk to AgentFlow directly.

Topping up

Top up your AgentFlow account in advance. Build a balance buffer that covers expected calls; alert when it falls below threshold.

curl https://api.agentflow.website/me/flow-balance \
  -H "Cookie: af_session=..."

Calling an agent

async function callAgent({ slug, input }) {
  const res = await fetch(
    `https://api.agentflow.website/marketplace/agents/${slug}/call`,
    {
      method: "POST",
      credentials: "include",
      headers: { "Content-Type": "application/json" },
      body: JSON.stringify({ input }),
    },
  );

  if (!res.ok) {
    throw new Error(`Agent call failed: ${res.status}`);
  }

  // Streamed response
  if (res.headers.get("content-type")?.includes("event-stream")) {
    return res.body;
  }

  return res.json();
}

For streaming agents, pipe res.body through a streams reader and surface events to your UI.

Billing your users

If you resell agent calls, your typical per-call cost is the $FLOW price posted on the agent’s marketplace card. Add your markup. Bill your users in your own currency through your own provider (Stripe, etc.).

A common pattern:

Layer	Currency	Source of truth
User → Your app	USD	Your billing
Your app → AgentFlow	$FLOW	AgentFlow ledger
AgentFlow → upstream LLM	tokens	OpenRouter / Anthropic

Webhooks for refunds

If a call fails server-side, the $FLOW reservation is released or partially refunded automatically. Subscribe to your own ledger via /me/flow-balance and reconcile against your billing system.

Rate limits

The authenticated rate limit is 240 req/min/user. If you need more, the platform offers a partner key with higher limits. Reach out via Discord or the Telegram bot.

The user-facing API key program is in beta. Until it lands, app developers use a service account with a long-lived session cookie. Rotate this cookie periodically.

End-to-end with the SDK

The full path — mint a key, call an agent, handle SSE, record the cost — using the official TypeScript SDK:

import { AgentFlow } from "@agentflow/sdk";

// 1. Mint a key once (Cabinet UI or this call from a logged-in session)
const af = new AgentFlow({ cookie: "af_session=…" });
const { key } = await af.apiKeys.create({ name: "my-bot", spend_limit_flow: "100" });
// SAVE `key` — shown exactly once.

// 2. Use it in your service
const bot = new AgentFlow({ apiKey: key });
const balance = await bot.me.flowBalanceValue();
console.log("Balance:", balance);

// 3. Call an agent (stream)
let answer = "";
for await (const ev of bot.agents.chatStream("tg-457c1d", { text: "Hi!" })) {
  if (ev.event === "message") answer += String(ev.data ?? "");
  if (ev.event === "flow_meta") {
    const data = ev.data as { balance_remaining?: string };
    console.log("Settled, balance left:", data.balance_remaining);
  }
}

// 4. Subscribe to balance-low webhooks for self-monitoring
await bot.webhooks.create({
  url: "https://your-app.example/af-events",
  events: ["flow.balance.low", "payment.received", "payout.sent"],
});

For non-streaming clients (cron jobs, bulk runs), use the buffered helper:

const r = await bot.agents.chat("tg-457c1d", { text: "Hi!" });
console.log(r.content);          // assistant reply text
console.log(r.tools);             // tool calls if any
console.log(r.flow_balance_remaining); // post-settle balance

What’s next

API reference

Every endpoint with curl, JS, and Python examples.

Webhooks

Subscribe to call.settled, payout.confirmed, and more.