> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mobula.io/llms.txt
> Use this file to discover all available pages before exploring further.

# filterPairs

> Search, filter, and rank trading pairs by on-chain statistics such as volume, price, liquidity, and trader metrics.

### Overview

Query trading pairs across all supported networks with filtering, sorting, and pagination. Ideal for building pair screeners and liquidity discovery tools.

* Filter by volume, price, liquidity, market cap, trader counts, and more
* Match pairs by specific token addresses with `matchTokens`
* Sort by any filterable attribute plus trending scores
* Paginate with `limit` / `offset`
* Optionally resolve full token metadata for both sides of the pair

### Returns

<ResponseField name="filterPairs" type="PairFilterConnection!">
  See [PairFilterConnection](/api-reference/graphql/types/PairFilterConnection) and [PairFilterResult](/api-reference/graphql/types/PairFilterResult) for full type details.
</ResponseField>

### Arguments

<ResponseField name="filters" type="PairFilters">
  Filter conditions for pair statistics. Each numeric field accepts a [NumberFilter](/api-reference/graphql/types/NumberFilter) with `gt`, `gte`, `lt`, `lte` operators. See [PairFilters](/api-reference/graphql/types/PairFilters) for all available fields.
</ResponseField>

<ResponseField name="statsType" type="TokenPairStatisticsType">
  Statistics type. See [TokenPairStatisticsType](/api-reference/graphql/types/TokenPairStatisticsType).
</ResponseField>

<ResponseField name="phrase" type="String">
  Search phrase to match against pair token names or symbols.
</ResponseField>

<ResponseField name="pairs" type="[String]">
  Array of specific pair selectors in `"address:networkId"` format.
</ResponseField>

<ResponseField name="matchTokens" type="PairFilterMatchTokens">
  Filter pairs by token addresses. See [PairFilterMatchTokens](/api-reference/graphql/types/PairFilterMatchTokens) for details.

  When both are provided, the pair must contain both tokens (in either order). When only one is provided, the pair must contain that token on either side.
</ResponseField>

<ResponseField name="rankings" type="[PairRanking]">
  Sorting criteria. See [PairRanking](/api-reference/graphql/types/PairRanking) and [PairRankingAttribute](/api-reference/graphql/types/PairRankingAttribute) for all sortable fields.
</ResponseField>

<ResponseField name="limit" type="Int">
  Maximum number of results to return (default: 25, max: 200).
</ResponseField>

<ResponseField name="offset" type="Int">
  Pagination offset (default: 0).
</ResponseField>

### Example

```graphql theme={null}
{
  filterPairs(
    filters: {
      network: [1]
      liquidity: { gte: 50000 }
      volumeUSD24: { gte: 100000 }
    }
    rankings: [{ attribute: volumeUSD24, direction: DESC }]
    limit: 10
  ) {
    results {
      price
      liquidity
      marketCap
      volumeUSD24
      priceChange24
      buyCount24
      sellCount24
      uniqueBuys24
      uniqueSells24
      pair {
        address
        networkId
        token0
        token1
        fee
      }
      token0 {
        name
        symbol
        address
      }
      token1 {
        name
        symbol
        address
      }
    }
    count
    offset
  }
}
```

### Using matchTokens

Filter pairs that include a specific token:

```graphql theme={null}
{
  filterPairs(
    matchTokens: { token0: "0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2" }
    filters: { liquidity: { gte: 10000 } }
    limit: 5
  ) {
    results {
      price
      liquidity
      volumeUSD24
      token0 { symbol }
      token1 { symbol }
    }
    count
  }
}
```

### Playground

<iframe src={`https://graphql.mobula.io/graphql?query=${encodeURIComponent('{ filterPairs(filters: { network: [1], liquidity: { gte: 50000 }, volumeUSD24: { gte: 100000 } }, rankings: [{ attribute: volumeUSD24, direction: DESC }], limit: 5) { results { price liquidity volumeUSD24 priceChange24 buyCount24 sellCount24 token0 { name symbol } token1 { name symbol } } count offset } }')}`} title="GraphQL Playground" style={{ width: '100%', minHeight: '600px', border: '1px solid var(--color-border)', borderRadius: '8px' }} />