Filters Guide

🚀 New to GMGN.ai? Create your account with our referral link to support GmGnAPI’s development → Sign up on GMGN.ai
💬 Need help? Join the Chipa Discord · ⚡ Go no-code with ChipaEditor

GmGnAPI’s filter system lets you define exactly which tokens fire your handlers. Filters run server-side before your callback — only matching tokens consume your processing time.

Quick Start

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 = 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:

@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

Tutorial 2 — Filtering Tokens — 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 GMGN account to explore the dashboard, understand the data, and build better filter strategies — signing up with our link supports GmGnAPI development. Want to tune filters without code? ChipaEditor makes it visual, and the Chipa Discord is full of filter presets shared by the community.