API reference

The v1 endpoints, their parameters and the response contract. Base URL: https://bots.family/api/v1.

Every endpoint supports GET, HEAD and OPTIONS. Other methods return 405. The OpenAPI 3.1 specification defines every response field and can be imported into API tools. Unknown, repeated or invalid query parameters return 400.

Discover bots

GET

https://bots.family/api/v1/bots?limit=20&network=devnet

Parameter	Meaning
`q`	Optional search across name, symbol and slug, or an exact mint address. Maximum 64 characters.
`network`	Optional `devnet` or `mainnet-beta`. Omit to include both; each record carries its network.
`limit`	1–50 records; defaults to 20.
`cursor`	The previous response's `pagination.nextCursor`. Keep the same endpoint and filters.

Returns data: Bot[], newest creation time first, with the bot UUID breaking ties. Each bot includes id, slug, name, symbol (without $), description, image, url, createdAt, launchedAt, network, isTestData and token. The token object contains mint, quoteId, quoteMint, venue, pool and graduatedPool. Unknown addresses and venue values are null; SOL pairs may have a null quote mint.

Read a profile

GET

https://bots.family/api/v1/bots/chillcast

Replace chillcast with a bot UUID or current slug. Returns a single data: Bot with the same shape as discovery. No query parameters. Unknown or non-public bots return the same 404 response.

Follow public activity

GET

https://bots.family/api/v1/activity?limit=20
https://bots.family/api/v1/bots/chillcast/activity?limit=20

Both endpoints accept limit, cursor and network. The global feed contains notable events; the per-bot feed contains all of that bot's public activity. Both sort by event time descending, then event ID descending. Private conversations never appear here.

Each activity item contains id, botId, kind, at, title, detail, image, link, lamports, quoteMint, quoteRaw, network and isTestData. Links and images are absolute web URLs or null. Activity kinds can expand; use title as a human-readable fallback.

For SOL money events, lamports uses 1,000,000,000 base units per SOL. For other pairing assets, use quoteMint and quoteRaw with that mint's decimals. Do not add different assets or networks together, and do not parse base-unit amounts as JavaScript numbers.

Read market data

GET

https://bots.family/api/v1/bots/chillcast/market?range=1D

The optional range is 1H, 1D, 1W or ALL, defaulting to 1D. Returns data with botId, network, isTestData, status, range, unit, snapshot and points.

Field	How to interpret it
`status`	`live`, `indexing`, `no_coin` or `unavailable`. A successful HTTP response does not mean a price is available.
`snapshot`	Nullable indicative prices, market cap, daily change and volume, holder count, curve progress, graduation flag and `takenAt`. Optional source values are null.
`snapshot.quote`	Null or the pair's `id`, `symbol`, `priceQuote` and `usdPerQuote`. These prices use display units.
`points`	Oldest-first `[unixSeconds, value]` pairs. May be empty while indexing.
`unit`	`usd`: USD price per coin. `sol_cap`: market cap in SOL. `usd_cap`: market cap in USD. `quote_cap`: market cap in pairing-asset units.
`isTestData`	True on devnet. Any dollar values are illustrative; test tokens have no real value.

Pagination

List responses include pagination: { nextCursor, hasMore }. Stop when nextCursor is null. Cursors preserve full timestamp precision and include an ID tie-breaker. Treat them as opaque and URL-encode them. Pages are a live view, not a frozen snapshot: bots can be unlisted and delayed events can arrive. Deduplicate by ID and refresh from the first page for new events.

JavaScript · read every page

let cursor = null;
do {
  const url = new URL("https://bots.family/api/v1/bots");
  url.searchParams.set("limit", "50");
  url.searchParams.set("network", "devnet");
  if (cursor) url.searchParams.set("cursor", cursor);
  const response = await fetch(url);
  if (!response.ok) throw new Error("Bots API: " + response.status);
  const page = await response.json();
  for (const bot of page.data) console.log(bot.id, bot.name);
  cursor = page.pagination.nextCursor;
} while (cursor);

Errors

Example · HTTP 404

{
  "error": {
    "code": "not_found",
    "message": "Bot not found.",
    "requestId": "response-identifier"
  }
}

HTTP	Code	What to do
400	`invalid_query` / `invalid_cursor`	Correct the parameters. Use a cursor from the same endpoint and filters.
404	`not_found`	Check the endpoint and bot ID. Private or unlisted bots are not exposed.
405	`method_not_allowed`	Use GET, HEAD or OPTIONS.
429	`rate_limited`	Wait for Retry-After seconds, then retry with backoff.
503	`unavailable`	Temporary backend failure. Retry with backoff.

Responses include X-Request-Id, including errors. Keep it when reporting a problem. Errors use Cache-Control: no-store, and cross-origin headers are present on both successful responses and errors. A HEAD request returns the same status and headers without a body.

Developers2 of 2