Search Service

Public, no-auth full-text search for Kumbaya tokens and pools. Backed by an in-memory index (MiniSearch) that's continuously synced.

Field	Value
Base URL	https://search.kumbaya.xyz
Base path	/api/v1
OpenAPI / Swagger	search.kumbaya.xyz/docs
Auth	None. Rate-limited per IP.

Building an LLM agent? These endpoints are also available as MCP tools - 8 of them under the search_ prefix. See the MCP Server, part of the Kumbaya Agent Kit.

Endpoints

Health

• GET /health - { status, indexed, tokenCount, poolCount }

• GET /ready - readiness probe (200 if synced, 503 until then)

Search (/api/v1/search*)

GET /api/v1/search - combined token + pool search

Query parameters:

Param	Type	Notes
q	string (1–256)	The search query - fuzzy matched on symbol, name, and address.
chainId	int	4326 mainnet, 6343 testnet
limit	int (1–100, default 20)	Max results
isBluechip	bool	Filter to blue-chip tokens/pools
isTrending	bool	Filter to trending
isFireToken / isFirePool	bool	Filter to launchpad-originated tokens / their pools
isVerified	bool	Filter to verified
visibility	verified | trusted | all	Visibility level

Response: { tokens: Token[], pools: Pool[], query, chainId }.

GET /api/v1/search/tokens - tokens only

Same query params; returns { tokens, query, chainId }.

GET /api/v1/search/pools - pools only

Same query params; returns { pools, query, chainId }.

GET /api/v1/autocomplete - fast prefix completion

For typeahead UIs. Returns either null or a single best suggestion:

{
  "query": "kum",
  "suggestion": {
    "completion": "Kumbaya",
    "symbol": "KUM",
    "name": "Kumbaya Token",
    "address": "0x…",
    "matchType": "name"        // or "symbol"
  }
}

Stricter rate limits than the main search endpoints.

Index introspection

• GET /api/v1/search/stats - { tokenCount, poolCount, lastSyncTime, syncInProgress }

• GET /api/v1/tokens - list all indexed tokens with the same filter params (no q required)

Token / pool fields

Tokens include: id, address, symbol, name, chainId, decimals, totalValueLockedUSD, volumeUSD, isBluechip, isTrending, isFireToken, isVerified, fireCreator, fireGraduated, imageUrl.

Pools include: id, address, chainId, feeTier, token0 { symbol, name, address }, token1 { … }, totalValueLockedUSD, volumeUSD, isBluechip, isFirePool, isVerified.

When to use this vs. the indexer

• Search service - typeahead, full-text matching, filtering for "show me launchpad tokens that are trending" style queries. Optimized for browser-grade latency.

• Hasura indexer - anything analytical, time-series, or filtered on numeric ranges. The search index doesn't do range queries on TVL or time-bounded counts.

• Exchange API - when you need quote pricing or detailed pool state, not search.

For complete schemas see Swagger at search.kumbaya.xyz/docs.