Token Search

Free-text search over every token we have pool coverage for — not just the curated catalog — by symbol and name, ranked so the deepest-liquidity match comes first. Or paste a mint address to resolve it directly.

GET /v1/tokens/search

Query parameters:

• q — (required) free text (symbol or name 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 and name across our pool-coverage universe, ordered by liquidity (deepest first), capped at limit, with source: "coverage".

Response:

{
  "query": "spacex",
  "results": [
    {
      "mint": "XxAv…YjF",
      "symbol": "SPACEX",
      "name": "SpaceX Token",
      "decimals": 6,
      "logoURI": "https://…/spacex.png",
      "priceUsd": 0.0142,
      "description": "…"
    }
  ],
  "count": 1,
  "source": "coverage"
}

Row fields: mint, symbol, name (never null — falls back to symbol), decimals, 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), description (null if none).

Ranking: by liquidity — the mint's deepest USD-anchored pool depth in our index. A deep, real token sorts above a thin clone matching the same text.

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"