Filter Types

Overview

Filters allow you to narrow down API results to specific criteria. Each endpoint supports different filters based on the data it returns.

Filter Types

NumericRangeFilter

Filter numeric values (floats) with optional min/max bounds.

Schema:

{
  "min": 1000.0,
  "max": 50000.0
}

Fields:

Field	Type	Description
min	float	Minimum value (inclusive)
max	float	Maximum value (inclusive)

Examples:

// Minimum only
{"min": 1000000}

// Maximum only
{"max": 50000}

// Range
{"min": 1000, "max": 1000000}

// Negative values allowed
{"min": -10.5, "max": 100.75}

Common Uses:

• value_usd - Filter by USD value

• price_usd - Filter by price

• market_cap_usd - Filter by market cap

• volume_24h_usd - Filter by volume

IntegerRangeFilter

Filter integer values with optional min/max bounds.

Schema:

{
  "min": 10,
  "max": 1000
}

Fields:

Field	Type	Description
min	integer	Minimum value (inclusive)
max	integer	Maximum value (inclusive)

Examples:

// Minimum holders
{"min": 100}

// Age range
{"min": 7, "max": 365}

Common Uses:

• holder_count - Filter by number of holders

• token_age_days - Filter by token age

• trade_count - Filter by number of trades

DateRangeFilter

Filter by date/time ranges.

Schema:

{
  "from": "2025-01-01T00:00:00Z",
  "to": "2025-01-31T23:59:59Z"
}

Fields:

Field	Type	Description
from	string	Start date (ISO 8601 format)
to	string	End date (ISO 8601 format)

Formats:

// Full datetime
"2025-01-01T00:00:00Z"

// Date only
"2025-01-01"

Examples:

// Last 7 days
{
  "from": "2025-01-07T00:00:00Z",
  "to": "2025-01-14T00:00:00Z"
}

// Specific month
{
  "from": "2025-01-01",
  "to": "2025-01-31"
}

TokenAddressFilter

Filter by one or more token addresses.

Schema:

"0x..."
// or
["0x...", "0x..."]

Examples:

// Single token
"token_address": "0x6982508145454ce325ddbe47a25d4ec3d2311933"

// Multiple tokens
"token_addresses": [
  "0x6982508145454ce325ddbe47a25d4ec3d2311933",
  "0xdac17f958d2ee523a2206206994597c13d831ec7"
]

TraderAddressFilter

Filter by one or more trader/wallet addresses.

Schema:

"0x..."
// or
["0x...", "0x..."]

Examples:

// Single trader
"trader_address": "0x28C6c06298d514Db089934071355E5743bf21d60"

// Multiple traders
"trader_addresses": [
  "0x28C6c06298d514Db089934071355E5743bf21d60",
  "0x47ac0Fb4F2D84898e4D9E7b4DaB3C24507a6D503"
]

LabelFilter

Filter by smart money or entity labels.

Schema:

["Fund", "Smart Trader"]

Smart Money Labels:

[
  "Fund",
  "Smart Trader",
  "30D Smart Trader",
  "90D Smart Trader",
  "180D Smart Trader",
  "Smart HL Perps Trader"
]

Extended Labels:

[
  "Public Figure",
  "Exchange",
  "Whale",
  "BananaGun Bot User",
  "Maestro Bot User"
]

Examples:

// Include funds and smart traders
"include_smart_money_labels": ["Fund", "Smart Trader"]

// Exclude exchanges
"exclude_labels": ["Exchange"]

SectorsFilter

Filter by token sector/category.

Schema:

["DeFi", "Meme"]

Common Sectors:

[
  "DeFi",
  "Meme",
  "Gaming",
  "NFT",
  "Infrastructure",
  "Layer 1",
  "Layer 2",
  "Stablecoin",
  "AI",
  "RWA"
]

Examples:

// DeFi tokens only
"sectors": ["DeFi"]

// Multiple sectors
"sectors": ["Meme", "Gaming"]

BooleanFilter

Simple true/false filter.

Schema:

true
// or
false

Examples:

// Hide spam tokens
"hide_spam_tokens": true

// Include only new positions
"only_new_positions": true

Filter Validation Rules

Range Filters

1. max must be greater than min if both provided

2. Some fields require positive values only

// Invalid - max less than min
{"min": 1000, "max": 500}

// Invalid for some fields - negative min
{"min": -100}

Date Filters

1. to must be after from

2. Maximum range is typically 1 year

// Invalid - to before from
{
  "from": "2025-12-31",
  "to": "2025-01-01"
}

Address Filters

1. Must match chain address format

2. Cannot be burn/zero addresses for some endpoints

Using Filters in Requests

Basic Filter Usage

response = client.post(
    "https://api.nansen.ai/api/v1/smart-money/holdings",
    json={
        "chains": ["ethereum"],
        "filters": {
            "value_usd": {"min": 100000},
            "include_smart_money_labels": ["Fund"]
        }
    }
)

Combining Multiple Filters

response = client.post(
    "https://api.nansen.ai/api/v1/token-screener",
    json={
        "chains": ["ethereum"],
        "filters": {
            "market_cap_usd": {"min": 1000000, "max": 100000000},
            "volume_24h_usd": {"min": 50000},
            "holder_count": {"min": 100},
            "token_age_days": {"min": 7},
            "sectors": ["DeFi", "Meme"],
            "hide_spam_tokens": true
        }
    }
)

Endpoint-Specific Filters

Different endpoints support different filters. Check each endpoint's documentation for available filters.