Filters Guide - GmGnAPI Documentation

Quick Start

quick_filter.py

from gmgnapi.filters import TokenFilter

# Only tokens that pass ALL conditions will trigger your handler
f = TokenFilter(
    min_market_cap=50_000,    # $50k minimum
    max_market_cap=2_000_000, # $2M maximum
    min_liquidity=10_000,     # $10k liquidity floor
    min_volume_1h=3_000,      # some hourly activity
    chains=["solana"],        # Solana only
)

All Filter Parameters

Market Cap

Parameter	Type	Description
`min_market_cap`	float	Minimum market cap in USD
`max_market_cap`	float	Maximum market cap in USD

Liquidity

Parameter	Type	Description
`min_liquidity`	float	Minimum pool liquidity in USD
`max_liquidity`	float	Maximum pool liquidity in USD

Volume

Parameter	Type	Description
`min_volume_1h`	float	Minimum 1-hour volume in USD
`min_volume_24h`	float	Minimum 24-hour volume in USD
`min_buy_count_1h`	int	Minimum number of buy transactions in 1h
`min_sell_count_1h`	int	Minimum number of sell transactions in 1h

Chain & Token

Parameter	Type	Description
`chains`	list[str]	e.g. `["solana"]`, `["eth","bsc"]`
`require_verified`	bool	Only include GMGN-verified tokens
`exclude_honeypots`	bool	Filter out detected honeypot contracts
`max_holder_concentration`	float (0–1)	Max % held by top wallet (e.g. 0.3 = 30%)

Starter Presets

Copy-paste these presets as a starting point and tune to your strategy.

Early Gem Sniper

presets.py

early_gem = TokenFilter(
    min_market_cap=10_000,
    max_market_cap=200_000,
    min_liquidity=5_000,
    min_volume_1h=1_000,
    chains=["solana"],
    exclude_honeypots=True,
)

mid_cap = TokenFilter(
    min_market_cap=500_000,
    max_market_cap=10_000_000,
    min_liquidity=50_000,
    min_volume_24h=100_000,
    require_verified=True,
)

high_volume = TokenFilter(
    min_volume_1h=50_000,
    min_buy_count_1h=100,
    max_holder_concentration=0.25,
)

Custom Filter Logic

For conditions not covered by TokenFilter, add a guard inside your handler:

custom_logic.py

@client.on_new_pool
async def on_pool(pool):
    # custom ratio check
    if pool.volume_1h / max(pool.liquidity, 1) < 0.1:
        return  # skip low activity

    # keyword filter on token name
    if any(word in pool.name.lower() for word in ["scam", "fake", "test"]):
        return

    print(f"Passed all checks: {pool.address}")

Keep Building

Filter Tutorial

Step-by-step walkthrough of building a filtered monitor.

Trading Bots

Use filters as entry signals in automated bots.

API Reference

Full TokenFilter class documentation.

Examples

Real-world filter combos used in production.

GMGN.ai — The Data Behind the Filters

Every filter parameter maps directly to GMGN.ai's live blockchain data. Create a free account to explore the dashboard, understand the data, and build better filter strategies.

Create Free GMGN Account →