> ## 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.

# Filter Details

> Complete reference for all available filters in Pulse Stream API

<Tip>
  **Mode Selection**: Pulse Stream V2 supports two modes:

  * **Asset Mode** (`assetMode: true`): Token-based filtering using `TokensStatsRealTime` schema
  * **Pool Mode** (`assetMode: false`): Pool-based filtering with nested `pools` filters
</Tip>

## Asset Mode Filter Structure

In Asset Mode, filters are applied directly to token statistics without nested `pools` filters:

```json theme={null}
{
  "assetMode": true,
  "filters": {
    "market_cap": { "gte": 1000, "lte": 100000 },
    "volume_1h": { "gte": 500 },
    "bonded": { "equals": false },
    "source": { "in": ["pumpfun", "moonshot-evm"] }
  }
}
```

## Pool Mode Filter Structure

In Pool Mode, pool-specific filters must be placed within the `pools` object:

```json theme={null}
{
  "assetMode": false,
  "filters": {
    "market_cap": { "gte": 1000, "lte": 100000 },
    "volume_1h": { "gte": 500 },
    "pools": {
      "type": { "in": ["pumpfun", "moonshot-evm"] },
      "bonded": { "equals": false },
      "factory": { "in": ["uniswap-v2", "meteora-dbc"] }
    }
  }
}
```

***

# Asset Mode Filters (assetMode: true)

<Note>
  These filters apply to token-based queries using the `TokensStatsRealTime` schema. Use these when `assetMode: true`.
</Note>

## Available Filter Fields (Asset Mode)

### Price Fields

* **`latest_price`** (number): Current price of the token
* **`price_1min_ago`** (number): Price 1 minute ago
* **`price_5min_ago`** (number): Price 5 minutes ago
* **`price_1h_ago`** (number): Price 1 hour ago
* **`price_4h_ago`** (number): Price 4 hours ago
* **`price_6h_ago`** (number): Price 6 hours ago
* **`price_12h_ago`** (number): Price 12 hours ago
* **`price_24h_ago`** (number): Price 24 hours ago
* **`ath`** (number): All-time high price in USD
* **`atl`** (number): All-time low price in USD
* **`ath_date`** (Date): Date when all-time high was reached
* **`atl_date`** (Date): Date when all-time low was reached

### Price Change Fields

* **`price_change_1min`** (number): Price change in 1 minute (%)
* **`price_change_5min`** (number): Price change in 5 minutes (%)
* **`price_change_1h`** (number): Price change in 1 hour (%)
* **`price_change_4h`** (number): Price change in 4 hours (%)
* **`price_change_6h`** (number): Price change in 6 hours (%)
* **`price_change_12h`** (number): Price change in 12 hours (%)
* **`price_change_24h`** (number): Price change in 24 hours (%)

### Market Cap Fields

* **`market_cap`** (number): Current market capitalization
* **`latest_market_cap`** (number): Latest market capitalization

### Volume Fields

* **`volume_1min`** (number): Volume in 1 minute
* **`volume_5min`** (number): Volume in 5 minutes
* **`volume_15min`** (number): Volume in 15 minutes
* **`volume_1h`** (number): Volume in 1 hour
* **`volume_4h`** (number): Volume in 4 hours
* **`volume_6h`** (number): Volume in 6 hours
* **`volume_12h`** (number): Volume in 12 hours
* **`volume_24h`** (number): Volume in 24 hours

### Volume Buy/Sell Fields

* **`volume_buy_1min`** (number): Buy volume in 1 minute
* **`volume_buy_5min`** (number): Buy volume in 5 minutes
* **`volume_buy_15min`** (number): Buy volume in 15 minutes
* **`volume_buy_1h`** (number): Buy volume in 1 hour
* **`volume_buy_4h`** (number): Buy volume in 4 hours
* **`volume_buy_6h`** (number): Buy volume in 6 hours
* **`volume_buy_12h`** (number): Buy volume in 12 hours
* **`volume_buy_24h`** (number): Buy volume in 24 hours
* **`volume_sell_1min`** (number): Sell volume in 1 minute
* **`volume_sell_5min`** (number): Sell volume in 5 minutes
* **`volume_sell_15min`** (number): Sell volume in 15 minutes
* **`volume_sell_1h`** (number): Sell volume in 1 hour
* **`volume_sell_4h`** (number): Sell volume in 4 hours
* **`volume_sell_6h`** (number): Sell volume in 6 hours
* **`volume_sell_12h`** (number): Sell volume in 12 hours
* **`volume_sell_24h`** (number): Sell volume in 24 hours

### Trades Fields

* **`trades_1min`** (number): Number of trades in 1 minute
* **`trades_5min`** (number): Number of trades in 5 minutes
* **`trades_15min`** (number): Number of trades in 15 minutes
* **`trades_1h`** (number): Number of trades in 1 hour
* **`trades_4h`** (number): Number of trades in 4 hours
* **`trades_6h`** (number): Number of trades in 6 hours
* **`trades_12h`** (number): Number of trades in 12 hours
* **`trades_24h`** (number): Number of trades in 24 hours

### Buys Fields

* **`buys_1min`** (number): Number of buy transactions in 1 minute
* **`buys_5min`** (number): Number of buy transactions in 5 minutes
* **`buys_15min`** (number): Number of buy transactions in 15 minutes
* **`buys_1h`** (number): Number of buy transactions in 1 hour
* **`buys_4h`** (number): Number of buy transactions in 4 hours
* **`buys_6h`** (number): Number of buy transactions in 6 hours
* **`buys_12h`** (number): Number of buy transactions in 12 hours
* **`buys_24h`** (number): Number of buy transactions in 24 hours

### Sells Fields

* **`sells_1min`** (number): Number of sell transactions in 1 minute
* **`sells_5min`** (number): Number of sell transactions in 5 minutes
* **`sells_15min`** (number): Number of sell transactions in 15 minutes
* **`sells_1h`** (number): Number of sell transactions in 1 hour
* **`sells_4h`** (number): Number of sell transactions in 4 hours
* **`sells_6h`** (number): Number of sell transactions in 6 hours
* **`sells_12h`** (number): Number of sell transactions in 12 hours
* **`sells_24h`** (number): Number of sell transactions in 24 hours

### Buyers Fields

* **`buyers_1min`** (number): Number of unique buyers in 1 minute
* **`buyers_5min`** (number): Number of unique buyers in 5 minutes
* **`buyers_15min`** (number): Number of unique buyers in 15 minutes
* **`buyers_1h`** (number): Number of unique buyers in 1 hour
* **`buyers_4h`** (number): Number of unique buyers in 4 hours
* **`buyers_6h`** (number): Number of unique buyers in 6 hours
* **`buyers_12h`** (number): Number of unique buyers in 12 hours
* **`buyers_24h`** (number): Number of unique buyers in 24 hours

### Sellers Fields

* **`sellers_1min`** (number): Number of unique sellers in 1 minute
* **`sellers_5min`** (number): Number of unique sellers in 5 minutes
* **`sellers_15min`** (number): Number of unique sellers in 15 minutes
* **`sellers_1h`** (number): Number of unique sellers in 1 hour
* **`sellers_4h`** (number): Number of unique sellers in 4 hours
* **`sellers_6h`** (number): Number of unique sellers in 6 hours
* **`sellers_12h`** (number): Number of unique sellers in 12 hours
* **`sellers_24h`** (number): Number of unique sellers in 24 hours

### Traders Fields

* **`traders_1min`** (number): Number of unique traders in 1 minute
* **`traders_5min`** (number): Number of unique traders in 5 minutes
* **`traders_15min`** (number): Number of unique traders in 15 minutes
* **`traders_1h`** (number): Number of unique traders in 1 hour
* **`traders_4h`** (number): Number of unique traders in 4 hours
* **`traders_6h`** (number): Number of unique traders in 6 hours
* **`traders_12h`** (number): Number of unique traders in 12 hours
* **`traders_24h`** (number): Number of unique traders in 24 hours

### Fees Paid Fields

* **`fees_paid_1min`** (number): Total fees paid in 1 minute
* **`fees_paid_5min`** (number): Total fees paid in 5 minutes
* **`fees_paid_15min`** (number): Total fees paid in 15 minutes
* **`fees_paid_1h`** (number): Total fees paid in 1 hour
* **`fees_paid_4h`** (number): Total fees paid in 4 hours
* **`fees_paid_6h`** (number): Total fees paid in 6 hours
* **`fees_paid_12h`** (number): Total fees paid in 12 hours
* **`fees_paid_24h`** (number): Total fees paid in 24 hours

### Organic Trading Data Fields (Excluding Bot Activity)

The organic metrics provide cleaner data by filtering out bot activity and MEV transactions.

#### Organic Trades

* **`organic_trades_1min`** (number): Number of organic trades in 1 minute
* **`organic_trades_5min`** (number): Number of organic trades in 5 minutes
* **`organic_trades_15min`** (number): Number of organic trades in 15 minutes
* **`organic_trades_1h`** (number): Number of organic trades in 1 hour
* **`organic_trades_4h`** (number): Number of organic trades in 4 hours
* **`organic_trades_6h`** (number): Number of organic trades in 6 hours
* **`organic_trades_12h`** (number): Number of organic trades in 12 hours
* **`organic_trades_24h`** (number): Number of organic trades in 24 hours

#### Organic Volume

* **`organic_volume_1min`** (number): Organic volume in 1 minute
* **`organic_volume_5min`** (number): Organic volume in 5 minutes
* **`organic_volume_15min`** (number): Organic volume in 15 minutes
* **`organic_volume_1h`** (number): Organic volume in 1 hour
* **`organic_volume_4h`** (number): Organic volume in 4 hours
* **`organic_volume_6h`** (number): Organic volume in 6 hours
* **`organic_volume_12h`** (number): Organic volume in 12 hours
* **`organic_volume_24h`** (number): Organic volume in 24 hours

#### Organic Buy/Sell Volume

* **`organic_volume_buy_1min`** (number): Organic buy volume in 1 minute
* **`organic_volume_buy_5min`** (number): Organic buy volume in 5 minutes
* **`organic_volume_buy_15min`** (number): Organic buy volume in 15 minutes
* **`organic_volume_buy_1h`** (number): Organic buy volume in 1 hour
* **`organic_volume_buy_4h`** (number): Organic buy volume in 4 hours
* **`organic_volume_buy_6h`** (number): Organic buy volume in 6 hours
* **`organic_volume_buy_12h`** (number): Organic buy volume in 12 hours
* **`organic_volume_buy_24h`** (number): Organic buy volume in 24 hours
* **`organic_volume_sell_1min`** (number): Organic sell volume in 1 minute
* **`organic_volume_sell_5min`** (number): Organic sell volume in 5 minutes
* **`organic_volume_sell_15min`** (number): Organic sell volume in 15 minutes
* **`organic_volume_sell_1h`** (number): Organic sell volume in 1 hour
* **`organic_volume_sell_4h`** (number): Organic sell volume in 4 hours
* **`organic_volume_sell_6h`** (number): Organic sell volume in 6 hours
* **`organic_volume_sell_12h`** (number): Organic sell volume in 12 hours
* **`organic_volume_sell_24h`** (number): Organic sell volume in 24 hours

#### Organic Buys/Sells

* **`organic_buys_1min`** (number): Number of organic buy transactions in 1 minute
* **`organic_buys_5min`** (number): Number of organic buy transactions in 5 minutes
* **`organic_buys_15min`** (number): Number of organic buy transactions in 15 minutes
* **`organic_buys_1h`** (number): Number of organic buy transactions in 1 hour
* **`organic_buys_4h`** (number): Number of organic buy transactions in 4 hours
* **`organic_buys_6h`** (number): Number of organic buy transactions in 6 hours
* **`organic_buys_12h`** (number): Number of organic buy transactions in 12 hours
* **`organic_buys_24h`** (number): Number of organic buy transactions in 24 hours
* **`organic_sells_1min`** (number): Number of organic sell transactions in 1 minute
* **`organic_sells_5min`** (number): Number of organic sell transactions in 5 minutes
* **`organic_sells_15min`** (number): Number of organic sell transactions in 15 minutes
* **`organic_sells_1h`** (number): Number of organic sell transactions in 1 hour
* **`organic_sells_4h`** (number): Number of organic sell transactions in 4 hours
* **`organic_sells_6h`** (number): Number of organic sell transactions in 6 hours
* **`organic_sells_12h`** (number): Number of organic sell transactions in 12 hours
* **`organic_sells_24h`** (number): Number of organic sell transactions in 24 hours

#### Organic Participants

* **`organic_buyers_1min`** (number): Number of unique organic buyers in 1 minute
* **`organic_buyers_5min`** (number): Number of unique organic buyers in 5 minutes
* **`organic_buyers_15min`** (number): Number of unique organic buyers in 15 minutes
* **`organic_buyers_1h`** (number): Number of unique organic buyers in 1 hour
* **`organic_buyers_4h`** (number): Number of unique organic buyers in 4 hours
* **`organic_buyers_6h`** (number): Number of unique organic buyers in 6 hours
* **`organic_buyers_12h`** (number): Number of unique organic buyers in 12 hours
* **`organic_buyers_24h`** (number): Number of unique organic buyers in 24 hours
* **`organic_sellers_1min`** (number): Number of unique organic sellers in 1 minute
* **`organic_sellers_5min`** (number): Number of unique organic sellers in 5 minutes
* **`organic_sellers_15min`** (number): Number of unique organic sellers in 15 minutes
* **`organic_sellers_1h`** (number): Number of unique organic sellers in 1 hour
* **`organic_sellers_4h`** (number): Number of unique organic sellers in 4 hours
* **`organic_sellers_6h`** (number): Number of unique organic sellers in 6 hours
* **`organic_sellers_12h`** (number): Number of unique organic sellers in 12 hours
* **`organic_sellers_24h`** (number): Number of unique organic sellers in 24 hours
* **`organic_traders_1min`** (number): Number of unique organic traders in 1 minute
* **`organic_traders_5min`** (number): Number of unique organic traders in 5 minutes
* **`organic_traders_15min`** (number): Number of unique organic traders in 15 minutes
* **`organic_traders_1h`** (number): Number of unique organic traders in 1 hour
* **`organic_traders_4h`** (number): Number of unique organic traders in 4 hours
* **`organic_traders_6h`** (number): Number of unique organic traders in 6 hours
* **`organic_traders_12h`** (number): Number of unique organic traders in 12 hours
* **`organic_traders_24h`** (number): Number of unique organic traders in 24 hours

### Holdings Analysis Fields

* **`bonding_percentage`** (number): Percentage of tokens in bonding phase
* **`dev_holdings_percentage`** (number): Percentage held by developers
* **`bundlers_holdings_percentage`** (number): Percentage held by bundlers
* **`insiders_holdings_percentage`** (number): Percentage held by insiders
* **`snipers_holdings_percentage`** (number): Percentage held by snipers
* **`deployer_migrations_count`** (number): Number of deployer migrations
* **`twitter_reuses_count`** (number): Number of Twitter handle reuses
* **`pro_traders_holdings_percentage`** (number): Percentage held by professional traders
* **`fresh_traders_holdings_percentage`** (number): Percentage held by fresh traders
* **`smart_traders_holdings_percentage`** (number): Percentage held by smart traders
* **`top_10_holdings_percentage`** (number): Percentage held by top 10 holders
* **`top_50_holdings_percentage`** (number): Percentage held by top 50 holders
* **`top_100_holdings_percentage`** (number): Percentage held by top 100 holders
* **`top_200_holdings_percentage`** (number): Percentage held by top 200 holders

### Trader Categories Count Fields

* **`insiders_count`** (number): Number of insider traders
* **`bundlers_count`** (number): Number of bundler traders
* **`snipers_count`** (number): Number of sniper traders
* **`fresh_traders_count`** (number): Number of fresh traders
* **`pro_traders_count`** (number): Number of professional traders
* **`smart_traders_count`** (number): Number of smart traders

### Trader Buys Tracking Fields

* **`fresh_traders_buys`** (number): Number of buys by fresh traders
* **`pro_traders_buys`** (number): Number of buys by professional traders
* **`smart_traders_buys`** (number): Number of buys by smart traders

### Metadata Fields

* **`tokenSymbol`** (string): Token symbol (e.g., "BTC", "ETH")
* **`tokenName`** (string): Token full name (e.g., "Bitcoin", "Ethereum")
* **`dexscreenerListed`** (boolean): Whether the token is listed on DexScreener

### Keyword Filter Fields

* **`includeKeywords`** (string\[]): Array of keywords that must be present in the token name or symbol (case insensitive)
* **`excludeKeywords`** (string\[]): Array of keywords that must NOT be present in the token name or symbol (case insensitive)

### Timeframe Filter Fields

* **`created_at_offset`** (object): Filter pools/tokens by creation time relative to now (values in seconds)
  * **`gte`** (number): Minimum age in seconds (e.g., 1800 for 30 minutes ago)
  * **`lte`** (number): Maximum age in seconds (e.g., 3600 for 1 hour ago)
  * **Note**: Values are in seconds, not milliseconds. The system converts them to relative timestamps.
* **`created_at`** (object): Filter pools/tokens by absolute creation date
  * **`gte`** (Date | string): Minimum creation date
  * **`lte`** (Date | string): Maximum creation date
* **`latest_trade_date`** (object): Filter pools/tokens by last trade date
  * **`gte`** (Date | string): Minimum last trade date
  * **`lte`** (Date | string): Maximum last trade date

### Other Token Fields

* **`holders_count`** (number): Number of token holders
* **`liquidity`** (number): Pool liquidity
* **`liquidity_max`** (number): Maximum liquidity reached
* **`created_at`** (Date): Token creation date
* **`latest_trade_date`** (Date): Last trade date
* **`bonded_at`** (Date): Bonding completion timestamp
* **`migrated_at`** (Date): Migration timestamp
* **`source`** (string): Source launchpad (e.g., "pumpfun", "moonshot-evm", "fourmeme")
* **`factory`** (string): Factory address
* **`pre_bonding_factory`** (string): Factory address before bonding
* **`pool_address`** (string): Associated pool address
* **`deployer`** (string): Address of the token deployer
* **`chainId`** (string): Blockchain identifier
* **`twitter`** (string): Twitter/X social media link
* **`telegram`** (string): Telegram social media link
* **`website`** (string): Website URL
* **`others`** (string): Other social links
* **`security`** (Json): Security analysis data
* **`logo`** (string): Token logo URL
* **`token_symbol`** (string): Token symbol
* **`token_name`** (string): Token name
* **`twitter_rename_count`** (number): Twitter rename count
* **`twitter_rename_history`** (Json): Twitter rename history
* **`dexscreener_listed`** (boolean): Whether listed on DexScreener
* **`dexscreener_header`** (string): DexScreener header status
* **`dexscreener_ad_paid`** (boolean): DexScreener ad paid status
* **`live_status`** (string): PumpLive livestream status ('pump\_live' for currently live, 'pump\_live\_end' for ended)
* **`live_thumbnail`** (string): PumpLive livestream thumbnail URL
* **`livestream_title`** (string): PumpLive livestream title
* **`bonded`** (boolean): Whether token is bonded

#### Mobula Mode Flags

These flags come from `tokens_stats_real_time` and are surfaced both at the root and inside the nested `token` object of the asset-mode pulse response. Each accepts both snake\_case and camelCase (e.g. `is_cashback_coin` or `isCashbackCoin`).

* **`is_cashback_coin`** (boolean): Token is enrolled in Mobula's cashback program (traders earn cashback on swaps)
* **`is_mayhem_mode`** (boolean): Token is flagged for Mobula's Mayhem mode
* **`is_agent_mode`** (boolean): Token is flagged for Agent mode
* **`is_og_coin`** (boolean | null): `true` when no other token on the same chain shares this token's `name` — the OG of that name on this chain. `false` when a prior same-name, same-chain token already exists (this one is a copycat / rename). `null` while still being resolved. Same-chain only — a name can be OG on multiple chains independently. Accepted as `is_og_coin` or `isOGCoin`.

### Security Fields

The `security` object contains token security analysis data. You can filter on individual security fields using dot notation (e.g., `security.buyTax`, `security.isBlacklisted`).

#### Numeric Security Fields (string format - use numeric operators)

* **`security.buyTax`** (string): Buy tax percentage (e.g., "0.0000", "5.0000"). Use numeric operators like `gte`, `lte`, `gt`, `lt`
* **`security.sellTax`** (string): Sell tax percentage (e.g., "0.0000", "10.0000"). Use numeric operators like `gte`, `lte`, `gt`, `lt`

#### Boolean Security Fields

* **`security.isBlacklisted`** (boolean): Whether the token has blacklist functionality
* **`security.balanceMutable`** (boolean): Whether token balances can be modified by the contract
* **`security.noMintAuthority`** (boolean): Whether mint authority has been revoked (Solana)
* **`security.transferPausable`** (boolean): Whether transfers can be paused

### Custom Filter Fields (Asset Mode)

These are special filters processed by the API that provide additional filtering capabilities.

* **`pattern`** (string): Search pattern for token symbol or name (case insensitive). Matches against `token_name` or `token_symbol`
* **`min_socials`** (number): Minimum number of social media links required (1, 2, or 3). Checks for presence of `twitter`, `telegram`, and `website` fields
* **`assetListed`** (boolean): Filter tokens that have a Mobula asset listing. When `true`, only officially listed tokens are returned
* **`includeKeywords`** (string\[]): Array of keywords that must be present in the token name or symbol (case insensitive)
* **`excludeKeywords`** (string\[]): Array of keywords that must NOT be present in the token name or symbol (case insensitive)
* **`assetListed`** (boolean): When `true`, only returns tokens that are officially listed (i.e., their address has an `assetId` that is not null). This corresponds to tokens that have verified metadata and appear in the Mobula asset registry. Useful to filter out unlisted/unverified tokens and keep only recognized assets.
* **`excludeLPTokens`** (boolean): Excludes LP wrapper tokens in Asset Mode by requiring `poolAddress` to be present. Default is `true`; set to `false` to include LP wrapper tokens explicitly.
* **`offset`** (number): Number of results to skip for pagination (use with `limit`)
* **`limit`** (number): Maximum number of results to return (max 100)
* **`sortBy`** (string): Field to sort by (e.g., "volume\_1h", "market\_cap", "created\_at")
* **`sortOrder`** ("asc" | "desc"): Sort direction
* **`addressToExclude`** (string | string\[]): Token address(es) to exclude from results

## Filter Operators

* **`equals`**: Exact equality
* **`gte`**: Greater than or equal
* **`lte`**: Less than or equal
* **`gt`**: Strictly greater than
* **`lt`**: Strictly less than
* **`not`**: Not equal to (useful for `not: null`)
* **`in`**: In the list
* **`contains`**: String contains (case sensitive by default, use with `mode: 'insensitive'` for case-insensitive)

***

## Asset Mode Filter Examples

These examples demonstrate filtering in Asset Mode (`assetMode: true`).

#### Price Filters

```json theme={null}
{
  "assetMode": true,
  "filters": {
    "latest_price": { "gte": 0.0001, "lte": 0.001 },
    "price_change_1h": { "gte": 10 },
    "price_change_24h": { "lte": -5 }
  }
}
```

#### All-Time High/Low Filters

```json theme={null}
{
  "assetMode": true,
  "filters": {
    "ath": { "gte": 1.0 },
    "atl": { "lte": 0.0001 }
  }
}
```

#### Market Cap Filters

```json theme={null}
{
  "assetMode": true,
  "filters": {
    "market_cap": { 
      "gte": 10000,
      "lte": 1000000,
      "not": null
    }
  }
}
```

#### Volume and Activity Filters

```json theme={null}
{
  "assetMode": true,
  "filters": {
    "volume_1h": { "gte": 1000 },
    "trades_24h": { "gte": 50 },
    "holders_count": { "gte": 100 }
  }
}
```

#### Volume Buy/Sell Filters

```json theme={null}
{
  "assetMode": true,
  "filters": {
    "volume_buy_1h": { "gte": 500 },
    "volume_sell_1h": { "lte": 300 },
    "volume_buy_24h": { "gte": 10000 },
    "volume_sell_24h": { "lte": 8000 }
  }
}
```

#### Trading Activity Filters

```json theme={null}
{
  "assetMode": true,
  "filters": {
    "buys_1h": { "gte": 10 },
    "sells_1h": { "lte": 20 },
    "buyers_24h": { "gte": 50 },
    "sellers_24h": { "lte": 30 },
    "traders_1h": { "gte": 25 },
    "fees_paid_24h": { "gte": 100 }
  }
}
```

#### Organic Trading Filters

```json theme={null}
{
  "assetMode": true,
  "filters": {
    "organic_volume_1h": { "gte": 5000 },
    "organic_trades_1h": { "gte": 50 },
    "organic_buyers_1h": { "gte": 30 }
  }
}
```

#### Holdings Analysis Filters

```json theme={null}
{
  "assetMode": true,
  "filters": {
    "bonding_percentage": { "gte": 50 },
    "dev_holdings_percentage": { "lte": 10 },
    "top_10_holdings_percentage": { "lte": 30 },
    "snipers_holdings_percentage": { "lte": 5 },
    "twitter_reuses_count": { "equals": 0 }
  }
}
```

#### Trader Categories Filters

```json theme={null}
{
  "assetMode": true,
  "filters": {
    "fresh_traders_count": { "gte": 10 },
    "pro_traders_count": { "gte": 5 },
    "smart_traders_buys": { "gte": 3 }
  }
}
```

#### Token Metadata Filters

```json theme={null}
{
  "assetMode": true,
  "filters": {
    "token_symbol": { "equals": "DOGE" },
    "token_name": { "equals": "Dogecoin" },
    "dexscreener_listed": { "equals": true }
  }
}
```

#### Date Filters

```json theme={null}
{
  "assetMode": true,
  "filters": {
    "created_at": { 
      "gte": "2024-01-01T00:00:00Z",
      "lte": "2024-12-31T23:59:59Z"
    },
    "latest_trade_date": { "gte": "2024-01-01T00:00:00Z" }
  }
}
```

#### Source and Deployer Filters

```json theme={null}
{
  "assetMode": true,
  "filters": {
    "source": { "equals": "pumpfun" },
    "deployer": { "equals": "0x123..." },
    "chainId": { "in": ["evm:8453", "solana:solana"] }
  }
}
```

#### Social Media Filters

```json theme={null}
{
  "assetMode": true,
  "filters": {
    "min_socials": 2,
    "twitter": { "not": null },
    "telegram": { "not": null }
  }
}
```

#### Pattern Search Filters

```json theme={null}
{
  "assetMode": true,
  "filters": {
    "pattern": "doge",
    "min_socials": 1
  }
}
```

#### Keyword Filters

```json theme={null}
{
  "assetMode": true,
  "filters": {
    "includeKeywords": ["meme", "doge", "cat"],
    "excludeKeywords": ["scam", "fake", "test"]
  }
}
```

#### Timeframe Offset Filters

```json theme={null}
{
  "assetMode": true,
  "filters": {
    "created_at_offset": {
      "gte": 1800,
      "lte": 3600
    }
  }
}
```

#### Address Exclusion Filters

```json theme={null}
{
  "assetMode": true,
  "filters": {
    "addressToExclude": ["0xAddress1...", "0xAddress2..."]
  }
}
```

#### LP Token Exclusion

```json theme={null}
{
  "assetMode": true,
  "filters": {
    "excludeLPTokens": true,
    "bonding_percentage": { "lt": 100 }
  }
}
```

In Asset Mode, `excludeLPTokens` defaults to `true`. Set it to `false` only when you explicitly want LP wrapper tokens such as Uniswap V2 token contracts in the response.

#### Security Filters

Filter tokens based on security analysis data. Use dot notation to access nested security fields.

**Filter by tax rates:**

```json theme={null}
{
  "assetMode": true,
  "filters": {
    "security": {
      "buyTax": { "lte": 5 },
      "sellTax": { "lte": 10 }
    }
  }
}
```

**Filter for safe tokens (no honeypot, no blacklist, mint revoked):**

```json theme={null}
{
  "assetMode": true,
  "filters": {
    "security": {
      "isHoneypot": { "equals": false },
      "isBlacklisted": { "equals": false },
      "noMintAuthority": { "equals": true }
    }
  }
}
```

**Filter for tokens with immutable balances and non-pausable transfers:**

```json theme={null}
{
  "assetMode": true,
  "filters": {
    "security": {
      "balanceMutable": { "equals": false },
      "transferPausable": { "equals": false }
    }
  }
}
```

**Filter for tokens with security data available:**

```json theme={null}
{
  "assetMode": true,
  "filters": {
    "security": { "not": null }
  }
}
```

**Combined security and market filters:**

```json theme={null}
{
  "assetMode": true,
  "filters": {
    "security": {
      "sellTax": { "lte": 5 },
      "isBlacklisted": { "equals": false },
      "noMintAuthority": { "equals": true }
    },
    "market_cap": { "gte": 10000 },
    "volume_1h": { "gte": 1000 }
  }
}
```

### Bonded Filter

The `bonded` filter provides a simplified way to filter pools based on their bonding status. This filter automatically converts to the appropriate pool filters:

* **`bonded: false`**: Filters for pools that are not bonded (launchpad pools)
  * Converts to: `pools: { bonded: { equals: false } }`

* **`bonded: true`**: Filters for pools that have bonded (new pools of tokens that have bonded)
  * Converts to: `pools: { bonded: { equals: false }, bondingCurveAddress: { not: null } }`

#### Bonded Filter Examples

```json theme={null}
{
  "filters": {
    "bonded": false,
    "market_cap": { "gte": 1000 }
  }
}
```

```json theme={null}
{
  "filters": {
    "bonded": true,
    "volume_1h": { "gte": 500 }
  }
}
```

**Note**: The `bonded: true` filter is equivalent to finding new pools of tokens that have already bonded, which is why it filters for `bonded: false` (launchpad pools) but with a `bondingCurveAddress` (indicating the token has bonded).

***

# Pool Mode Filters (assetMode: false)

<Note>
  These filters apply to pool-based queries. Use these when `assetMode: false` or when assetMode is not specified. Pool-specific filters must be placed within the `pools` object.
</Note>

## Available Filter Fields (Pool Mode)

Pool Mode supports most of the same token statistics fields as Asset Mode, but requires pool-specific filters to be nested under the `pools` object.

### Token Statistics Fields

All the token statistics fields from Asset Mode are available in Pool Mode (price, volume, trades, buyers, sellers, etc.). Refer to the Asset Mode section above for the complete list.

## Pool-Specific Filters

Pool filters allow filtering on pool properties based on the `Pool` schema relationship. These are specified directly under `filters.pools`.

### Available Pool Filter Fields

#### Pool Properties

* **`pools.type`** (string): Pool type (e.g., "pumpfun", "uniswap-v2", "raydium")
* **`pools.factory`** (string | string\[]): Factory contract address or name
* **`pools.bonded`** (boolean): Whether the pool is bonded
* **`pools.explicit`** (boolean): Whether the pool is explicit
* **`pools.token0_id`** (number): Token 0 ID
* **`pools.token1_id`** (number): Token 1 ID
* **`pools.base_id`** (number): Base token ID
* **`pools.price`** (number): Pool price
* **`pools.createdAt`** (Date): Pool creation date
* **`pools.chainId`** (string): Pool blockchain

### Pool Filter Examples

#### Pool Type Filters

```json theme={null}
{
  "filters": {
    "pools": {
      "type": { "in": ["pumpfun", "moonshot-evm"] },
      "bonded": { "equals": false }
    }
  }
}
```

#### Factory Filters with Name Resolution

```json theme={null}
{
  "filters": {
    "pools": {
      "factory": { "equals": "uniswap-v2" }
    }
  }
}
```

#### Token ID Filters

```json theme={null}
{
  "filters": {
    "pools": {
      "OR": [
        { "token0_id": { "in": [451088832, 451088651] } },
        { "token1_id": { "in": [451088832, 451088651] } }
      ]
    }
  }
}
```

#### Pool Creation Date Filters

```json theme={null}
{
  "filters": {
    "pools": {
      "createdAt": { "gte": "2024-01-01T00:00:00Z" },
      "explicit": { "equals": true }
    }
  }
}
```

### Custom Filter Fields (Pool Mode)

These are special filters processed by the API for Pool Mode.

* **`pattern`** (string): Search pattern for base token symbol or name (case insensitive)
* **`min_socials`** (number): Minimum number of social media links required (1, 2, or 3)
* **`assetListed`** (boolean): When `true`, only returns pools whose base token is officially listed (i.e., has an `assetId` not null). Also available in Asset Mode — see [Custom Filter Fields (Asset Mode)](#custom-filter-fields-asset-mode).
* **`includeKeywords`** (string\[]): Array of keywords that must be present in the base token name or symbol (case insensitive)
* **`excludeKeywords`** (string\[]): Array of keywords that must NOT be present in the base token name or symbol (case insensitive)
* **`offset`** (number): Number of results to skip for pagination (use with `limit`)
* **`limit`** (number): Maximum number of results to return (max 100)
* **`sortBy`** (string): Field to sort by
* **`sortOrder`** ("asc" | "desc"): Sort direction
* **`addressToExclude`** (string | string\[]): Address(es) to exclude from results (excludes pools containing these addresses as token0, token1, or pool address)
* **`baseTokenToExclude`** (string | string\[]): Base token address(es) to exclude from results

***

## Pool Mode Filter Examples

These examples demonstrate filtering in Pool Mode (`assetMode: false` or not specified).

### Basic Pool Filtering

#### Pool Type Filters

```json theme={null}
{
  "filters": {
    "pools": {
      "type": { "in": ["pumpfun", "moonshot-evm"] },
      "bonded": { "equals": false }
    }
  }
}
```

#### Factory Filters

```json theme={null}
{
  "filters": {
    "pools": {
      "factory": { "equals": "uniswap-v2" }
    }
  }
}
```

#### Token ID Filters

```json theme={null}
{
  "filters": {
    "pools": {
      "OR": [
        { "token0_id": { "in": [451088832, 451088651] } },
        { "token1_id": { "in": [451088832, 451088651] } }
      ]
    }
  }
}
```

#### Pool Creation Date Filters

```json theme={null}
{
  "filters": {
    "pools": {
      "createdAt": { "gte": "2024-01-01T00:00:00Z" },
      "explicit": { "equals": true }
    }
  }
}
```

#### Combined Pool and Token Filters

```json theme={null}
{
  "filters": {
    "volume_1h": { "gte": 1000 },
    "market_cap": { "gte": 10000 },
    "pools": {
      "type": { "in": ["pumpfun"] },
      "bonded": { "equals": false }
    }
  }
}
```

### Advanced Pool Mode Examples

#### Keyword Filters (Pool Mode)

```json theme={null}
{
  "filters": {
    "includeKeywords": ["meme", "dog"],
    "excludeKeywords": ["scam"],
    "pools": {
      "type": { "in": ["pumpfun", "moonshot-evm"] }
    }
  }
}
```

#### Address Exclusion (Pool Mode)

```json theme={null}
{
  "filters": {
    "addressToExclude": ["0xAddress1...", "0xAddress2..."],
    "pools": {
      "type": { "in": ["uniswap-v2", "uniswap-v3"] }
    }
  }
}
```

#### Base Token Exclusion (Pool Mode)

```json theme={null}
{
  "filters": {
    "baseTokenToExclude": ["0xUSDC...", "0xUSDT..."],
    "volume_1h": { "gte": 500 },
    "pools": {
      "type": { "in": ["raydium-v4"] }
    }
  }
}
```

#### Asset Listed Filter (Both Modes)

Filter to only return tokens/pools that are officially listed in the Mobula asset registry (i.e., their address has an `assetId` not null). Works in both Asset Mode and Pool Mode.

**Asset Mode** — filter tokens directly:

```json theme={null}
{
  "assetMode": true,
  "filters": {
    "assetListed": true,
    "volume_1h": { "gte": 1000 },
    "market_cap": { "gte": 50000 }
  }
}
```

**Pool Mode** — filter pools where the base token is listed:

```json theme={null}
{
  "filters": {
    "assetListed": true,
    "volume_1h": { "gte": 1000 },
    "market_cap": { "gte": 10000 },
    "pools": {
      "type": { "in": ["uniswap-v2", "aerodrome"] }
    }
  }
}
```

This is useful for focusing only on tokens/pools with verified metadata that appear in the Mobula asset registry.