@motosan-whale/nansen

Layer 1: Nansen API client for smart money discovery.

Part of the motosan-whale SDK — agent-first whale tracking tools.

Install

pnpm add @motosan-whale/nansen

Usage

import { NansenClient } from '@motosan-whale/nansen'

const nansen = new NansenClient({ apiKey: process.env.NANSEN_KEY! })

const tokens = await nansen.screenTokens({ chains: ['solana'], timeframe: '24h' })
const netflow = await nansen.getSmartMoneyNetflow({ chains: ['solana'] })
const labels = await nansen.getAddressPremiumLabels({ chain: 'ethereum', address: '0x...' })

API

NansenClient — Nansen REST API client with built-in retry, rate limiting, and timeout.

Token Screener

| Method | Endpoint | Description | |--------|----------|-------------| | screenTokens() | POST /api/v1/token-screener | Discover and screen tokens across chains |

Smart Money

| Method | Endpoint | Description | |--------|----------|-------------| | getSmartMoneyNetflow() | POST /api/v1/smart-money/netflow | Net capital flows by token | | getSmartMoneyDexTrades() | POST /api/v1/smart-money/dex-trades | DEX trades by smart money wallets | | getSmartMoneyPerpTrades() | POST /api/v1/smart-money/perp-trades | Hyperliquid perp trades by smart money | | getSmartMoneyDCAs() | POST /api/v1/smart-money/dcas | Jupiter DCA strategies by smart money | | getSmartMoneyHoldings() | POST /api/v1/smart-money/holdings | Aggregated token balances held by smart money | | getSmartMoneyHistoricalHoldings() | POST /api/v1/smart-money/historical-holdings | Historical token holdings by smart money |

Profiler

| Method | Endpoint | Description | |--------|----------|-------------| | getAddressLabels() | POST /api/v1/profiler/address/labels | Non-premium labels (ENS, DeFi, CEX) | | getAddressPremiumLabels() | POST /api/v1/profiler/address/premium-labels | All labels including smart money labels | | getAddressCurrentBalance() | POST /api/v1/profiler/address/current-balance | Current token holdings for an address | | getAddressHistoricalBalances() | POST /api/v1/profiler/address/historical-balances | Historical token balances | | getAddressTransactions() | POST /api/v1/profiler/address/transactions | Transaction history for a wallet | | getAddressPnlSummary() | POST /api/v1/profiler/address/pnl-summary | Realized PnL summary | | getAddressPnl() | POST /api/v1/profiler/address/pnl | Per-token PnL breakdown | | getAddressRelatedWallets() | POST /api/v1/profiler/address/related-wallets | Wallets related through on-chain interactions | | getAddressCounterparties() | POST /api/v1/profiler/address/counterparties | Counterparty analysis with volume breakdowns |

Profiler (Hyperliquid)

| Method | Endpoint | Description | |--------|----------|-------------| | getAddressPerpPositions() | POST /api/v1/profiler/address/perp-positions | Current perp positions on Hyperliquid | | getAddressPerpTrades() | POST /api/v1/profiler/address/perp-trades | Perp trade history on Hyperliquid | | getAddressPerpLeaderboard() | POST /api/v1/profiler/address/hyperliquid-address-leaderboard | Hyperliquid perp trading leaderboard |

Token God Mode (TGM)

| Method | Endpoint | Description | |--------|----------|-------------| | getTgmTokenInformation() | POST /api/v1/tgm/token-information | Token overview: name, symbol, metrics | | getTgmNansenIndicators() | POST /api/v1/tgm/nansen-indicators | Nansen proprietary indicators for a token | | getTgmPriceOhlcv() | POST /api/v1/tgm/price-ohlcv | OHLCV price candle data | | getTgmFlowIntelligence() | POST /api/v1/tgm/{chain}/{token}/flow-intelligence | Flow breakdown by wallet category | | getTgmHolders() | POST /api/v1/tgm/{chain}/{token}/holders | Token holder list with balance changes | | getTgmFlows() | POST /api/v1/tgm/{chain}/{token}/flows | Token flows by label category | | getTgmWhoBoughtSold() | POST /api/v1/tgm/{chain}/{token}/who-bought-sold | Wallets that bought/sold in a timeframe |

TGM Trades

| Method | Endpoint | Description | |--------|----------|-------------| | getTgmDexTrades() | POST /api/v1/tgm/dex-trades | DEX trades for a specific token | | getTgmTokenTransfers() | POST /api/v1/tgm/transfers | Token transfers for a specific token | | getTgmJupiterDCAs() | POST /api/v1/tgm/jup-dca | Jupiter DCA strategies for a token (Solana) | | getTgmPnlLeaderboard() | POST /api/v1/tgm/pnl-leaderboard | PnL leaderboard for a specific token |

TGM Perps (Hyperliquid)

| Method | Endpoint | Description | |--------|----------|-------------| | getTgmPerpScreener() | POST /api/v1/tgm/perp-screener | Hyperliquid perpetual market screener | | getTgmPerpPositions() | POST /api/v1/tgm/perp-positions | Open perp positions for a token symbol | | getTgmPerpTrades() | POST /api/v1/tgm/perp-trades | Recent perp trades for a token symbol | | getTgmPerpPnlLeaderboard() | POST /api/v1/tgm/perp-pnl-leaderboard | Perp PnL leaderboard for a token |

Portfolio

| Method | Endpoint | Description | |--------|----------|-------------| | getPortfolioDefiHoldings() | POST /api/v1/portfolio/defi-holdings | DeFi position breakdown (LP, lending, staking) |

License

MIT