---
title: "Full-text DEX pair and token search"
method: GET
path: "/api/v1/crypto/dex/search"
tags: ["Crypto"]
---

# Full-text DEX pair and token search

`GET /api/v1/crypto/dex/search`

Free-text search across every DEX pair and token indexed on-chain. Accepts ticker symbols, token names, or pair addresses; results are ranked upstream by volume and relevance across all supported chains. Sugra trims the response to the requested `limit` (max 50). Sourced from on-chain DEX data.

## Query parameters

- `q` string, required — Search query. Accepts ticker symbols (PEPE, SOL), project names, or pair addresses.
- `limit` integer — Maximum number of pair records to return after trimming upstream results.

## Response `200`

Pair records matched by the on-chain DEX search index, ranked upstream by volume and relevance.

- EnvelopeDexSearchPayload
  - `data` DexSearchPayload, required — Response payload for /api/v1/crypto/dex/search.
    - `query` string, required — Search query echoed back.
    - `schema_version` string, nullable — Upstream schema version.
    - `limit` integer, required — Client-requested page size (trimmed from upstream results).
    - `count` integer, required — Number of pair records returned after trimming.
    - `count_all` integer, required — Total pair matches before trimming.
    - `pairs` DexPair[], required — Pair records ranked by upstream relevance and volume.
      - `chainId` string, nullable — Blockchain slug (ethereum, solana, bsc, polygon, base, arbitrum, optimism, avalanche, etc.).
      - `dexId` string, nullable — DEX identifier (uniswap, raydium, pancakeswap, etc.).
      - `url` string, nullable — Canonical pair page URL.
      - `pairAddress` string, nullable — On-chain pair (liquidity pool) contract address.
      - `labels` string[], nullable — Upstream labels (e.g. `v2`, `v3`, `stable`) where relevant.
      - `baseToken` DexToken — Base or quote token within a DEX pair.
        - `address` string, nullable — On-chain token contract address. EVM chains use 0x-prefixed hex; Solana uses base58.
        - `name` string, nullable — Token display name as reported by upstream.
        - `symbol` string, nullable — Token ticker symbol.
      - `quoteToken` DexToken — Base or quote token within a DEX pair.
        - `address` string, nullable — On-chain token contract address. EVM chains use 0x-prefixed hex; Solana uses base58.
        - `name` string, nullable — Token display name as reported by upstream.
        - `symbol` string, nullable — Token ticker symbol.
      - `priceNative` string, nullable — Price of base in units of quote, as a string to preserve precision.
      - `priceUsd` string, nullable — Price of base in USD, as a string to preserve precision.
      - `txns` DexTxns — Transaction counts at four rolling windows.
        - `m5` DexTxnsInterval — Buy/sell transaction counts within a rolling window.
          - `buys` integer, nullable — Buy transactions in the window.
          - `sells` integer, nullable — Sell transactions in the window.
        - `h1` DexTxnsInterval — Buy/sell transaction counts within a rolling window.
          - `buys` integer, nullable — Buy transactions in the window.
          - `sells` integer, nullable — Sell transactions in the window.
        - `h6` DexTxnsInterval — Buy/sell transaction counts within a rolling window.
          - `buys` integer, nullable — Buy transactions in the window.
          - `sells` integer, nullable — Sell transactions in the window.
        - `h24` DexTxnsInterval — Buy/sell transaction counts within a rolling window.
          - `buys` integer, nullable — Buy transactions in the window.
          - `sells` integer, nullable — Sell transactions in the window.
      - `volume` DexVolume — Quote-denominated trade volume at rolling windows (USD where reported).
        - `m5` number, nullable — Rolling 5-minute volume.
        - `h1` number, nullable — Rolling 1-hour volume.
        - `h6` number, nullable — Rolling 6-hour volume.
        - `h24` number, nullable — Rolling 24-hour volume.
      - `priceChange` DexPriceChange — Percent price change at rolling windows.
        - `m5` number, nullable — Rolling 5-minute price change (percent).
        - `h1` number, nullable — Rolling 1-hour price change (percent).
        - `h6` number, nullable — Rolling 6-hour price change (percent).
        - `h24` number, nullable — Rolling 24-hour price change (percent).
      - `liquidity` DexLiquidity — Pair liquidity broken down by side (USD total, plus base/quote amounts).
        - `usd` number, nullable — Total liquidity in the pair (USD).
        - `base` number, nullable — Base-token amount in the pair.
        - `quote` number, nullable — Quote-token amount in the pair.
      - `fdv` number, nullable — Fully diluted valuation of the base token (USD). May be null for illiquid tokens.
      - `marketCap` number, nullable — Market capitalization of the base token (USD). May be null.
      - `pairCreatedAt` integer, nullable — Pair creation time (UNIX milliseconds). Pair birth, NOT snapshot time.
      - `info` DexPairInfo — Optional presentational block attached to a pair (imagery, links).
        - `imageUrl` string, nullable — Token logo URL.
        - `header` string, nullable — Token header/banner image URL.
        - `openGraph` string, nullable — Open Graph card URL for social previews.
        - `websites` DexPairLink[], nullable — Declared project websites.
          - `url` string, nullable — Link URL.
          - `label` string, nullable — Link label (Website, Whitepaper, etc.) when supplied.
          - `type` string, nullable — Link type (twitter, telegram, discord, etc.) when supplied.
        - `socials` DexPairLink[], nullable — Social profile links.
          - `url` string, nullable — Link URL.
          - `label` string, nullable — Link label (Website, Whitepaper, etc.) when supplied.
          - `type` string, nullable — Link type (twitter, telegram, discord, etc.) when supplied.
  - `meta` SugraMeta, required — Metadata attached to every /api/v1/* response envelope.
    - `endpoint` string, required — Requested endpoint path.
    - `data_time` string, required — ISO 8601 UTC timestamp of the source data, not of the request.
    - `response_time` string, required — ISO 8601 UTC timestamp when this response was produced.
    - `provider` string, required — API name and version.
    - `source` string, nullable — Identifier of the primary upstream source used for this response.
    - `attribution` string, nullable — Human-readable attribution mandated by an upstream source (e.g. a securities regulator or self-regulatory organization). Present only on responses whose source requires the owner and source to be clearly identified. Do not remove or alter it when using the response.
    - `fallback_used` boolean, nullable — True when the primary source failed and a fallback produced the data.
    - `fallback_chain` string[], nullable — Ordered list of sources attempted, in the order they were tried.
    - `cached` boolean, nullable — True when this response was served from the internal cache.
    - `stale` boolean, nullable — True when the cached response was returned after the upstream rate-limited or errored. Clients can use this to detect degraded data.

## Other responses

- `401` — Missing or invalid `x-api-key` header. JSON body with a stable `code` distinguishing `missing_api_key` (no header sent) from `invalid_api_key` (header sent, key not accepted); any other 401 source carries the generic `unauthorized` with its detail as `reason`. Plus `hint`. `plan` is always null on 401 - an unauthenticated request has no plan; quota exhaustion is 429, not 401.
- `422` — Validation Error
- `429` — Daily rate limit exceeded. Check `X-RateLimit-Reset` for the next window.
- `503` — Upstream source is temporarily unavailable. Retry after a short delay.

---

[API](https://skmtc.net/sugra/apis/sugra-api.md) · [All operations](https://skmtc.net/sugra/apis/sugra-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/sugra/sugra-api/versions/d3e3d9c28132/schema)