Tokens API

Off-chain metadata for tokens launched through factory.launch(). On-chain queries via the chain indexer.

The Tokens API is a thin metadata layer on top of the on-chain LaunchpadFactory and the per-template instances. The actual launch is always wallet-initiated — the API does not custody keys. These endpoints handle:

• Pre-flight metadata (name, ticker, description, image, tags) before signing.
• Post-launch reconciliation (linking instance address to a slug, AI-fill, image upload).
• Read-side queries from the chain indexer (state, holders, trades).

POST /tokens

Register off-chain metadata for a token you are about to launch (or just launched). Auth: required.

template · string · required

One of virtuals, dpnm. More templates added as they ship.

name · string · required

Display name.

ticker · string · required

3–6 character symbol.

brief · string

Optional short description; AI uses this to fill richer metadata.

params · object · required

Template-specific parameters. Shape differs per template — see Create a Token.

instance · address

Optional. If you’ve already deployed via factory.launch(...), pass the resulting instance address; the API will skip its own launch flow and just store metadata.

chainId · number · required

Chain to launch on. 97 = BSC testnet, 56 = BSC mainnet (when live), 8453 = Base mainnet (Phase 2).

curl

curl -X POST https://api.agentflow.website/tokens \
  -H "Content-Type: application/json" \
  -H "Cookie: af_session=..." \
  -d '{
    "template": "dpnm",
    "name": "Hermes Token",
    "ticker": "HERMES",
    "brief": "AI dispatcher token",
    "chainId": 97,
    "params": {
      "initialPrice": "0.1",
      "dailyLimitFloor": "50",
      "incomeLimitMultiplier": 2,
      "treeActivationCost": "10"
    }
  }'

Response

{
  "id": "tok_01HQ...",
  "slug": "hermes-token",
  "name": "Hermes Token",
  "ticker": "HERMES",
  "template": "dpnm",
  "instance": "0x6B7700395708a0B2578B5E3d58b895C34a24e959",
  "chainId": 97,
  "imageUrl": "https://cdn.agentflow.website/tokens/...",
  "state": "live",
  "createdAt": "2026-04-26T10:31:00Z"
}

If instance was not provided in the request, the response also includes a pendingLaunchTx field with the encoded calldata for the user’s wallet to sign.

GET /tokens

List tokens. Public.

Query params: cursor, template (virtuals | dpnm), state (live, graduating, sentient, failed), chainId, sort.

GET /tokens/:slug

Fetch full token state including on-chain reads from the chain indexer. Public.

{
  "slug": "hermes-token",
  "name": "Hermes Token",
  "ticker": "HERMES",
  "template": "virtuals",
  "instance": "0x...",
  "chainId": 97,
  "state": "graduating",
  "progressToGraduation": 0.83,
  "lockedPaymentToken": "34860",
  "graduationThreshold": "42000",
  "estimatedTimeToGraduation": "2d 14h",
  "holdersCount": 412,
  "lastTradePrice": "0.0042"
}

For dpnm tokens, the response shape differs:

{
  "slug": "flow",
  "ticker": "FLOW",
  "template": "dpnm",
  "instance": "0x2680b933af7a874d20954b03F38C86891A786511",
  "flowProtocol": "0x7F20f8e6e5077a4E11A1A2Fe54449ab55D32f653",
  "phenomenalTree": "0x9E12238d24Eece9b7575a53b17e36515eaEE0A30",
  "gwt": "0x40711d364b680ad7e85429bd36d7237E4e960783",
  "currentPrice": "0.1234",
  "poolUsdt": "150000",
  "totalSupply": "1216000",
  "holdersCount": 89,
  "treeActivePositions": 73
}

GET /tokens/:slug/holders

List token holders, paginated. Public. Reads from the chain indexer.

{
  "items": [
    { "address": "0xabc...", "balance": "12500000", "share": 0.0125 }
  ],
  "nextCursor": "..."
}

GET /tokens/:slug/trades

List recent buys and sells (and graduations for virtuals). Sourced from swap_events in the chain indexer.

Errors

Code	When
ticker_taken	Ticker already in use
invalid_ticker	Out of allowed character range
template_unknown	Template id not registered on this chain
params_invalid	Param shape does not match the template
chain_unsupported	chainId not configured
token_not_found	Slug does not exist

All on-chain interactions (launch, buy, sell, activate, extendTree, claimGWT, etc.) happen directly from the user’s wallet. The API never signs on the user’s behalf.