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

# Filtering and sorting

> Rank and filter discovery boards, and narrow trade lists by wallet classification.

Discovery boards and trade lists both narrow what they return. This page covers both: ranking and filtering a board, and narrowing a trade list by wallet classification.

## Discovery boards

`POST /v1/discovery` returns ranked boards of launchpad tokens. Each board is one stage of a token's launchpad life:

| Column | Holds | Default ranking |
| - | - | - |
| `newPairs` | Launchpad tokens below 40% of their bonding curve | `createdAt`, newest first |
| `graduating` | Launchpad tokens at 40% of their curve or more, not yet graduated | `bondingCurveActivity`, highest first |
| `graduated` | Launchpad tokens that have graduated, or that have no curve reading | `graduatedAt`, newest first |

### Request

Name the chains, and one or more columns. Each column is ranked and filtered on its own.

```json theme={null}
{
  "chains": ["solana", "base"],
  "graduating": {
    "sortBy": "volume24hUsd",
    "order": "desc",
    "limit": 20,
    "filters": {
      "liquidityUsd": { "min": "20000" },
      "holderCount": { "min": 500 },
      "excludeSymbolOrName": ["test"]
    }
  }
}
```

| Field | Meaning |
| - | - |
| `chains` | Required. One or more [chain slugs](/concepts/chains). Each column ranks tokens from all of them as one set. |
| `newPairs`, `graduating`, `graduated` | Leave a column out to skip it. Send `{}` to get it with its defaults. Name at least one. |
| `sortBy` | The field to rank on. Leave it out for the column's default. |
| `order` | `desc` (default) or `asc`. |
| `limit` | Tokens in the column, from 1 to 100. Default `20`. A value outside the range is moved into it. |
| `filters` | Conditions every token in the column must meet. See [Filters](#filters). |

### Column defaults

Every column applies conditions of its own, on top of your filters:

* **Every column** leaves out tokens with no update in the last 24 hours.
* **`graduating` and `graduated`** keep only tokens with at least 10 holders, $1,000 of liquidity and a $5,000 market cap.
* **`graduating`** also leaves out tokens with no update in the last 60 minutes, unless they are at 99.5% of their curve or more.

Your filters can tighten these conditions but not loosen them. A `holderCount` minimum below 10 on `graduated`, for example, is raised to 10, and a `maxGraduationStaleMinutes` above 60 on `graduating` is lowered to 60.

### Sort fields

| `sortBy` | Ranks on |
| - | - |
| `createdAt` | Token creation time |
| `volume24hUsd` | USD volume over the last 24 hours |
| `marketCapUsd` | USD market cap |
| `liquidityUsd` | USD liquidity |
| `holdersCount` | Current holders |
| `tradeCount24h` | Buys plus sells over the last 24 hours |
| `bondingCurvePct` | Bonding-curve completion. On `graduating`, this ranks on `bondingCurveActivity` instead. |
| `bondingCurveActivity` | Curve completion weighted by the last hour's volume: `bondingCurvePct × ln(1 + stats["1h"].volume.usd)` |
| `graduatedAt` | Graduation time |

Tokens with equal values keep a fixed order.

### Response

```json theme={null}
{
  "columns": [
    {
      "column": "graduating",
      "deltas": [
        { "chain": "solana", "address": "TokenMint1111111111111111111111111111111pump", "rank": 1, "data": { "symbol": "EXAMPLE", "bondingCurvePct": "91.4" } }
      ]
    }
  ]
}
```

`columns` holds one entry per requested column, in the order `newPairs`, `graduating`, `graduated`. Each entry's `deltas` is the whole ranked column. Every item has a `rank` from 1, and `data` holds the full [token object](/reference/streams/spot-tokens#update).

## Filters

A token must meet every filter you send, as well as the [column defaults](#column-defaults).

<Warning>
  The API ignores a filter name it does not know, rather than refusing it. Check spellings: the sort field is `holdersCount`, but the filter is `holderCount`.
</Warning>

### Ranges

A range is `{ "min": …, "max": … }`. Both bounds are inclusive, and either can be left out. A `min` above `max` returns `400 VALIDATION_ERROR`.

Each bound takes the type of the field it bounds: decimal strings for USD values, numbers for counts and percentages.

| Filter | Bound type | Meaning |
| - | - | - |
| `liquidityUsd` | Decimal string | USD liquidity |
| `marketCapUsd` | Decimal string | USD market cap |
| `volumeUsd` | Decimal string | USD volume over the last 24 hours |
| `globalFeesPaidUsd` | Decimal string | All-time USD fees traders paid to pools and launchpads |
| `holderCount` | Integer | Current holders |
| `txns` | Integer | Buys plus sells over the last 24 hours |
| `buys` | Integer | Buys over the last 24 hours |
| `sells` | Integer | Sells over the last 24 hours |
| `ageMinutes` | Integer | Minutes since the token was created |
| `bondingCurvePercent` | Number, 0–100 | Bonding-curve completion |
| `devHoldingPercent` | Number, 0–100 | Share of supply the creator holds |
| `top10HoldersPercent` | Number, 0–100 | Share of supply the 10 largest holders hold |
| `snipersSupplyPercent` | Number, 0–100 | Share of supply sniper wallets hold |

```json theme={null}
{ "marketCapUsd": { "min": "50000", "max": "5000000" }, "devHoldingPercent": { "max": 5 } }
```

### Lists

| Filter | Meaning |
| - | - |
| `protocols` | Keep tokens from any of these launchpads, such as `pumpfun`. The value `mayhem_mode` keeps Pump.fun Mayhem Mode tokens. |
| `anchorSymbols` | Keep tokens whose deepest pool prices against any of these quote assets, such as `WSOL`, `USDC` or `WBNB`. |
| `symbolOrName` | Keep tokens whose symbol or name contains any of these words, ignoring case. A word that looks like an address matches the token's address exactly instead. |
| `excludeSymbolOrName` | Drop tokens whose symbol or name contains any of these words, ignoring case. |
| `excludeWebsites` | Drop tokens whose website host matches any entry, as a URL or a bare domain. |
| `excludeTwitter` | Drop tokens whose X handle matches any entry, as a handle or a URL. |
| `excludeDevAddresses` | Drop tokens created by any of these wallets. |
| `excludeFundingAddresses` | Drop tokens whose creator was funded by any of these wallets. |

### Switches and time limits

| Filter | Type | Meaning |
| - | - | - |
| `withAtLeastOneSocial` | Boolean | `true` keeps tokens with at least one social link. |
| `withTwitter` | Boolean | `true` keeps tokens with an X link. |
| `withWebsite` | Boolean | `true` keeps tokens with a website. |
| `withTelegram` | Boolean | `true` keeps tokens with a Telegram link. |
| `lastActivityMinutes` | Integer | Keep tokens updated within this many minutes. |
| `maxGraduationStaleMinutes` | Integer | Drop tokens with no update within this many minutes, unless they are at 99.5% of their curve or more. It applies on any column; `graduating` caps it at 60. |

`false` or a missing switch applies no condition. An update is any change to a token's record, such as a trade, not only curve progress.

<Note>
  `twitterReuseCount` is accepted but not yet applied: every token passes it.
</Note>

## Trade lists

`GET /v1/tokens/{chain}/{address}/trades` narrows trades with query parameters:

| Parameter | Meaning |
| - | - |
| `flags` | A comma-separated list of [wallet classifications](/resources/glossary#wallet-classifications), such as `sniper,bundler`. Keeps trades whose trader carries any of them. `fomo` keeps trades routed through the fomo.family terminal. |
| `trader` | One wallet address. Keeps only that wallet's trades. |

```bash theme={null}
curl "https://{{API_HOST}}/v1/tokens/solana/DezXAZ8z7PnrnRJjz3wXBoRgixCa6xjnB7YaB1pPB263/trades?flags=sniper,bundler&limit=50" \
  -H "Authorization: Bearer $API_KEY"
```

An unknown `flags` value returns `400 VALIDATION_ERROR`. The same classifications filter the [`spot.trades`](/reference/streams/spot-trades) stream, where `fomo` also keeps trades with no known terminal by wallets flagged `fomo`.

`GET /v1/trades` takes `identity` (`kol` or `fomoscan`) and an optional `chains` list, such as `chains=solana,base`. Leave `chains` out to cover every chain.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.