Nansen Python SDK

An unofficial Python SDK for the Nansen blockchain analytics API, built as an internal build day project. While not an official Nansen product, it is fully functional if you'd like to use it.

Installation

pip install nansen

Development

git clone https://github.com/nansen-ai/nansen-python-sdk.git
cd nansen-python-sdk
uv sync --all-extras --dev

Quick Start

from nansen import Nansen

client = Nansen(api_key="your-api-key")  # or set NANSEN_API_KEY env var

# Smart Money holdings with auto-pagination
for item in client.smart_money.holdings(chains=["ethereum"]):
    print(f"{item.token_symbol}: ${item.value_usd:,.2f}")

client.close()

Async Support

import asyncio
from nansen import AsyncNansen

async def main():
    async with AsyncNansen() as client:
        page = await client.smart_money.holdings(chains=["ethereum"])
        async for item in page:
            print(item.token_symbol)

asyncio.run(main())

Pagination

All paginated endpoints return SyncPage / AsyncPage objects that auto-iterate across pages:

# Iterate all items across all pages
for item in client.smart_money.holdings(chains=["ethereum"]):
    print(item.token_symbol)

# Or work with individual pages
page = client.smart_money.holdings(chains=["ethereum"])
print(page.data)          # Current page items
print(page.has_next_page) # Check if more pages exist

for p in page.iter_pages():
    print(f"Page {p.pagination.page}: {len(p.data)} items")

Error Handling

from nansen import Nansen, RateLimitError, AuthenticationError, NansenError

try:
    page = client.smart_money.holdings(chains=["ethereum"])
except AuthenticationError:
    print("Invalid API key")
except RateLimitError as e:
    print(f"Rate limited, retry after {e.retry_after}s")
except NansenError as e:
    print(f"API error: {e}")

Exception hierarchy:

• NansenError — base
  • APIError — HTTP errors (has .status_code, .message, .body)
    • BadRequestError (400)
    • AuthenticationError (401)
    • PermissionDeniedError (403)
    • NotFoundError (404)
    • UnprocessableEntityError (422)
    • RateLimitError (429) — has .retry_after
    • InternalServerError (500)
    • GatewayTimeoutError (504)
  • APIConnectionError — network errors
    • APITimeoutError

Credits & Rate Limits

Every response includes rate limit and credit info:

resp = client.portfolio.defi_holdings(wallet_address="0x...")
print(resp.rate_limit.credits_used)
print(resp.rate_limit.credits_remaining)
print(resp.rate_limit.remaining_second)
print(resp.rate_limit.remaining_minute)

The SDK automatically retries on 429/5xx errors with exponential backoff (configurable):

client = Nansen(api_key="...", max_retries=3, timeout=30.0)

API Reference

Smart Money (client.smart_money)

Method	Description
.netflow(chains=...)	Net capital flows
.dex_trades(chains=...)	DEX trading activity
.perp_trades()	Perpetual trades (Hyperliquid)
.dcas()	DCA patterns (Jupiter/Solana)
.holdings(chains=...)	Current holdings
.historical_holdings(date_range=..., chains=...)	Historical holdings

Profiler (client.profiler)

Method	Description
.address.current_balance(chain=..., address=...)	Token balances
.address.historical_balances(chain=..., date=...)	Historical balances
.address.transactions(address=..., chain=..., date=...)	Transaction history
.address.counterparties(chain=..., date=...)	Top counterparties
.address.related_wallets(address=..., chain=...)	Related wallets
.address.labels(chain=..., address=...)	Address labels (beta)
.pnl_summary(chain=..., date=...)	PnL summary
.pnl(chain=...)	Detailed PnL per token
.perp_positions(address=...)	Open perp positions
.perp_trades(address=..., date=...)	Perp trade history
.entity_search(search_query=...)	Search entity names
.perp_leaderboard(date=...)	Perp leaderboard

Token God Mode (client.tgm)

Method	Description
.token_screener(chains=...)	Token screener
.token_information(chain=..., token_address=..., timeframe=...)	Token details
.flow_intel(chain=..., token_address=...)	Flow intelligence
.holders(chain=..., token_address=...)	Token holders
.flows(chain=..., token_address=..., date=...)	Token flows
.who_bought_sold(chain=..., token_address=..., date=...)	Buyer/seller analysis
.dex_trades(chain=..., token_address=..., date=...)	DEX trades for token
.transfers(chain=..., token_address=..., date=...)	Token transfers
.dcas(token_address=...)	Jupiter DCAs
.pnl_leaderboard(chain=..., token_address=..., date=...)	PnL leaderboard
.perp_screener(date=...)	Perp screener
.perp_pnl_leaderboard(token_symbol=..., date=...)	Perp PnL leaderboard
.perp_positions(token_symbol=...)	Perp positions
.perp_trades(token_symbol=..., date=...)	Perp trades

Portfolio (client.portfolio)

Method	Description
.defi_holdings(wallet_address=...)	DeFi holdings

Points (client.points)

Method	Description
.leaderboard(tier=...)	Points leaderboard (public, no auth)

Examples

The examples/ directory contains runnable scripts for every SDK endpoint. Each try_*.py script demonstrates a single endpoint with sample output formatting.

export NANSEN_API_KEY="your-key"
uv run python examples/try_token_screener.py
uv run python examples/try_smart_money_netflow.py
uv run python examples/try_address_balance.py
# ... etc

Script	Endpoint
try_token_screener.py	Token screener
try_token_information.py	Token details
try_flow_intel.py	Flow intelligence
try_holders.py	Token holders
try_flows.py	Token flows
try_who_bought_sold.py	Buyer/seller analysis
try_tgm_dex_trades.py	DEX trades (token)
try_transfers.py	Token transfers
try_tgm_dcas.py	Jupiter DCAs
try_pnl_leaderboard.py	PnL leaderboard
try_perp_screener.py	Perp screener
try_perp_pnl_leaderboard.py	Perp PnL leaderboard
try_tgm_perp_positions.py	Perp positions (token)
try_tgm_perp_trades.py	Perp trades (token)
try_smart_money.py	Smart Money holdings
try_smart_money_netflow.py	Smart Money netflow
try_smart_money_dex_trades.py	Smart Money DEX trades
try_smart_money_perp_trades.py	Smart Money perp trades
try_smart_money_dcas.py	Smart Money DCAs
try_smart_money_historical_holdings.py	Smart Money historical holdings
try_portfolio.py	DeFi holdings
try_entity_search.py	Entity search
try_profiler_pnl.py	PnL summary + detailed
try_profiler_perp.py	Perp positions + trades (profiler)
try_perp_leaderboard.py	Perp leaderboard
try_address_balance.py	Address current balance
try_address_historical_balances.py	Address historical balances
try_address_transactions.py	Address transactions
try_address_counterparties.py	Address counterparties
try_address_related_wallets.py	Address related wallets
try_address_labels.py	Address labels (beta)
try_points.py	Points leaderboard (no auth)

See also basic_usage.py, async_usage.py, and error_handling.py for general SDK usage patterns.

Requirements

• Python 3.10+
• httpx
• pydantic v2
• anyio