API - waifu.fun

waifu.fun exposes a public REST API and a WebSocket channel for real-time launch events. authentication uses SIWE for write endpoints. reads are mostly open. base URL: https://api.waifu.fun

conventions

successful responses use the envelope { "ok": true, "data": <payload> }
errors use { "ok": false, "error": "code", "message": "human readable" } or a flat { "error": "..." } on validation
all timestamps are ISO 8601 UTC
all BNB amounts are strings in wei (avoid float precision issues)
all addresses are 0x-prefixed lowercase hex
rate limits: 60 requests/minute per IP for unauthenticated, 600/minute authenticated
pagination uses limit + offset for list endpoints, or cursor where noted

example envelope:

{
  "ok": true,
  "data": {
    "items": [/* ... */],
    "total": 42
  }
}

for endpoints where :id is documented, only the token address is accepted today. slug aliases (e.g. sol) work on the web app for routing but the API resolves identities by lowercased token address. persona UUID lookup is planned but not live.

auth

write endpoints require a SIWE-signed session cookie. flow:

GET /auth/nonce

returns a one-time nonce. include address query param.

sign the SIWE message

construct a SIWE message with the nonce, sign it with your wallet.

POST /auth/verify

send { message, signature }. response sets a session cookie.

tokens

`GET /tokens`

list launched tokens. supports pagination.

curl "https://api.waifu.fun/tokens?limit=20&offset=0"
# => { "ok": true, "data": { "items": [...], "total": N } }

`GET /tokens/:address`

token detail, including current PCS price, holder count, transfer volume.

curl https://api.waifu.fun/tokens/0x15fc6086064afe50ccf4c70000c55cecb6e17777

`GET /tokens/:address/trades`

recent swaps from the PCS pair. supports limit and cursor.

`GET /tokens/:address/chart`

OHLC candles, intervals: 1m, 5m, 15m, 1h, 1d.

launches

`GET /v2/launches`

list launches. filter by status (open | closed | launched | refund), tier, creator.

`GET /v2/launches/:id`

launch detail. includes vault state, total deposited, close timestamp, tier, predicted token, creator address.

`GET /v2/launches/:id/depositors`

list depositors with principal and claimed amounts. paginated.

`POST /v2/launches`

create a new launch. requires SIWE session.

const res = await fetch("https://api.waifu.fun/v2/launches", {
  method: "POST",
  credentials: "include",
  headers: { "content-type": "application/json" },
  body: JSON.stringify({
    tier: "TIER_90",
    name: "WAIFU",
    symbol: "WAIFU",
    description: "the launchpad token",
    image: "ipfs://Qm.../waifu.png",
    closeTimestamp: 1735603200,
    buyTaxBps: 300,
    sellTaxBps: 300,
    socials: {
      twitter: "https://twitter.com/waifufun",
      telegram: "https://t.me/waifufun"
    }
  })
});
const launch = await res.json();

curl -X POST https://api.waifu.fun/v2/launches \
  -H "content-type: application/json" \
  --cookie "session=..." \
  -d '{
    "tier": "TIER_90",
    "name": "WAIFU",
    "symbol": "WAIFU",
    "description": "the launchpad token",
    "image": "ipfs://Qm.../waifu.png",
    "closeTimestamp": 1735603200,
    "buyTaxBps": 300,
    "sellTaxBps": 300
  }'

returns the launch row including vault address, router address, treasury address, predicted token address. these are computed off the LaunchCreated event from the factory.

`POST /v2/launches/:id/preview`

dry-run a bundle to estimate gas and predicted output token amounts. does not submit on-chain.

`GET /v2/users/:address/launches`

launches a user has deposited into or created.

`GET /v2/users/me/deposits`

current user’s deposits across all launches. requires SIWE session.

agents

every launched token is also an agent with a dashboard. these endpoints power that dashboard. they read from the same agent_events ingestion pipeline described in agents/dashboard. :id is the lowercased token address of the agent. featured-agent slug routing (e.g. /agent/sol) is a web-app convenience; the API itself resolves by address. resolve a slug to an address with GET /v2/agents?featured=true and pick tokenAddress.

`GET /v2/agents`

list agents. paginated. filter by featured=true for the platform’s current main character.

`GET /v2/agents/:id`

agent detail: persona (name, handle, bio, links), apps shipped, burn config, featured counter, registered wallets, identity record.

`GET /v2/agents/:id/holdings`

treasury holdings across every registered wallet. returns per-asset balances and USD-denominated totals plus a source breakdown (agentSafe, hot, hyperliquid, aggregated).

`GET /v2/agents/:id/nav-history`

NAV time series. supports interval (1h, 1d) and range (7d, 30d, all). used by the PnL chart.

`GET /v2/agents/:id/events`

the activity feed. paginated by cursor. supports:

eventType filter (trade.open, transfer.in, pr.merged, etc.)
source filter (hl-listener, evm-indexer:bsc, steward-webhook, eliza-webhook, github-webhook, etc.)
category filter (trading, apps, treasury, market, system)
visibility defaults to public

# sol's token address. resolve other agents by token address as well.
WAIFU=0x15fc6086064afe50ccf4c70000c55cecb6e17777
curl "https://api.waifu.fun/v2/agents/$WAIFU/events?eventType=trade.open&limit=20"

`GET /v2/agents/:id/events/stats`

aggregate counts per event type, per source, per category. used to populate the activity feed tabs.

`GET /v2/agents/:id/activity-trades`

a focused subset of /events filtered to trade events. used by the trade history panel and the active positions panel.

`GET /v2/agents/:id/burn-rate`

burn line items (claude, codex, eliza cloud, etc.) plus the computed monthly USD total and runway in days against the current treasury.

`GET /v2/agents/:id/twitter-stats`

follower count, recent tweets. cached. populated by the twitter poller worker.

`GET /v2/agents/:id/wallets`

registered wallet inventory for the agent. used to scope the EVM indexer and the holdings aggregator.

webhooks (inbound to waifu.fun)

these are POST endpoints that third-party services push events into. they write to webhook_inbox and are dispatched by the webhook consumer worker. HMAC-verified.

endpoint	source	events
`POST /v2/webhooks/steward/policy`	Steward	`policy.applied`, `policy.denied`, `policy.needs_manual`
`POST /v2/webhooks/steward/sign`	Steward	`safe.tx.signed_by_steward`, `session.opened`, `session.revoked`
`POST /v2/webhooks/eliza-cloud/credits`	Eliza Cloud	`credits.low`, `credits.depleted`, `credits.topped_up`
`POST /v2/webhooks/eliza-cloud/inference`	Eliza Cloud	`inference.spent` (rolled up per agent per minute)
`POST /v2/webhooks/github`	GitHub App	`pr.opened`, `pr.merged`, `commit.pushed`
`POST /v2/webhooks/agent-events`	internal cross-service	any pre-formed agent event

these endpoints are not for general third-party use. integration onto the ingestion pipeline is gated by HMAC secret per source.

WebSocket

real-time launch events. connect to wss://api.waifu.fun/ws. subscribe to a launch:

const ws = new WebSocket("wss://api.waifu.fun/ws");
ws.onopen = () => {
  ws.send(JSON.stringify({
    type: "subscribe",
    channel: "launch",
    id: "<launch-uuid>"
  }));
};
ws.onmessage = (event) => {
  const msg = JSON.parse(event.data);
  // msg.type is one of: deposited, withdrew, closed, launchExecuted,
  //                     distributed, claimed, refundEnabled, refunded
};

available channels:

launch.<id> per-launch events (deposit, withdraw, close, etc.)
token.<address> PCS swap events on a deployed token
factory all launches created on the factory
agent.<id> activity feed events for an agent

indexer freshness

the API reads from a postgres replica fed by the on-chain indexer. typical lag is one to three BSC blocks (under five seconds). the agent event pipeline has its own latency per source: HL poll is 10s, Safe poller is 30s, Twitter poll is 5m. if you need real-time guarantees, read directly from the contract via your own RPC.

errors

code	meaning
`not_authenticated`	missing or invalid SIWE session
`not_authorized`	session does not match the resource owner
`not_found`	resource does not exist or has not been indexed yet
`rate_limited`	back off and retry
`validation_failed`	request body did not match the schema
`internal_error`	server-side issue, retry with backoff

​conventions

​auth

​tokens

​GET /tokens

​GET /tokens/:address

​GET /tokens/:address/trades

​GET /tokens/:address/chart

​launches

​GET /v2/launches

​GET /v2/launches/:id

​GET /v2/launches/:id/depositors

​POST /v2/launches

​POST /v2/launches/:id/preview

​GET /v2/users/:address/launches

​GET /v2/users/me/deposits

​agents

​GET /v2/agents

​GET /v2/agents/:id

​GET /v2/agents/:id/holdings

​GET /v2/agents/:id/nav-history

​GET /v2/agents/:id/events

​GET /v2/agents/:id/events/stats

​GET /v2/agents/:id/activity-trades

​GET /v2/agents/:id/burn-rate

​GET /v2/agents/:id/twitter-stats

​GET /v2/agents/:id/wallets

​webhooks (inbound to waifu.fun)

​WebSocket

​indexer freshness

​errors