Token Search

Free-text search over every token we have pool coverage for — not just the curated catalog — by symbol, name and description, ranked by match relevance and then by vault-verified liquidity, so the real token tops the impersonators sharing its symbol. Or paste a mint address to resolve it directly.

GET /v1/tokens/search

Query parameters:

• q — (required) free text (symbol, name or description substring, e.g. spacex) or a full mint address.
• limit — (optional, default 20, max 50) number of results.

Behavior:

• If q is a mint address → resolved on-chain and returned as a single result with source: "on-chain" (works even for a mint we don't index).
• Otherwise → case-insensitive substring match on symbol, name and description across our pool-coverage universe, ordered by match relevance, then vault-verified liquidity (see Ranking below), capped at limit, with source: "coverage".

Response envelope (stable contract):

The top-level shape is { query, results, count, source } and is stable — new fields are only ever added (to the envelope or to rows), never removed or renamed. count equals results.length; source is "coverage" for text search or "on-chain" for a mint-address resolve.

{
  "query": "spacex",
  "results": [
    {
      "mint": "XxAv…YjF",
      "symbol": "SPACEX",
      "name": "SpaceX Token",
      "decimals": 6,
      "logoURI": "https://…/spacex.png",
      "logoProxyURI": "https://api.venum.dev/v1/tokens/XxAv…YjF/logo",
      "priceUsd": 0.0142,
      "liquidityUsd": 48210.5,
      "lowLiquidity": false,
      "poolCount": 7,
      "poolCacheAgeMs": 850,
      "description": "…"
    }
  ],
  "count": 1,
  "source": "coverage"
}

Row fields: mint, symbol, name (never null — falls back to symbol), decimals (JSON number), logoURI (null if unresolved), logoProxyURI (a Venum-hosted, CORS-open, non-redirecting copy — /v1/tokens/:mint/logo; null if no logo), priceUsd (from our own pools; null if unpriceable), liquidityUsd (see below; null if unmeasurable), lowLiquidity (see below), poolCount (how many pools we index for the mint — market breadth; clones typically have 1), poolCacheAgeMs (age of the freshest pool state behind priceUsd, same semantics as /v1/prices; real markets tick constantly, dead tokens sit stale for hours; null when unpriced), description (null if none).

Rows also carry updateAuthority — the metadata update authority, the strongest on-chain issuer anchor (null when absent or not yet resolved). For tokens claiming to be securities, match it against the issuer keys you trust; an impersonator can fake a name but not the issuer's signing key.

Together liquidityUsd + lowLiquidity + poolCount + poolCacheAgeMs + updateAuthority are the legitimacy/activity heuristic kit: verified capital, breadth, recency, and issuer identity — all measured from our own indexed on-chain state.

Ranking + liquidityUsd: rows with less than $1,000 of verified liquidity (or unmeasurable liquidity) are flagged lowLiquidity: true and always sort below every adequately-liquid row — real markets outrank dust and impersonators regardless of how well the dust matches the text. Within each liquidity class, rows are ordered by text-match relevance (exact symbol → symbol prefix / exact name → substring → name → description), then by liquidityUsd within each relevance tier — so typing bonk puts the exact-symbol BONK above a deeper token that merely mentions bonk in its name. Treat lowLiquidity: true as a warning signal in UIs (badge it, or require an explicit tap-through), especially for tokens claiming to be securities or majors. liquidityUsd is the USD (USDC/USDT/SOL-side) capital actually held on-chain in the token's deepest USD-paired pool, verified against the pool vault's real balance. Pool-claimed state (a concentrated-liquidity price pushed to fiction by a dust trade) is never trusted, so an impersonator can't buy rank without depositing real USDC/SOL. A deep, real token sorts above a thin clone matching the same text; a priced token sorts above an unpriceable one at equal depth. Use liquidityUsd as the legitimacy signal when several rows share a symbol — clones show null or dust-level values. (priceUsd alone is NOT a legitimacy signal: for a thin listing the pool is the market, so a manipulated pool can display an arbitrary price.)

Description matching is best-effort: descriptions come from each token's off-chain metadata, which we resolve lazily (first time a token appears in a search page or is fetched individually). A description-only match lights up after the token has been seen once.

Coverage: free-text search finds a token once we've indexed a pool for it and warmed its on-chain name/symbol (a background process). A brand-new long-tail token may not be name-searchable for a short window after listing — paste its mint address to resolve it immediately in the meantime.

Errors: 400 INVALID_REQUEST when q is missing/empty. See Error Handling.

Example:

curl -H "x-api-key: $VENUM_API_KEY" \
  "https://api.venum.dev/v1/tokens/search?q=spacex&limit=10"