npm package: @motosan-whale/nansen
Description: Nansen API client for smart money discovery and whale tracking
Latest version: 0.1.5

# @motosan-whale/nansen

> Layer 1: Nansen API client for smart money discovery.

Part of the [motosan-whale](https://github.com/daiwanwei/motosan-whale) SDK — agent-first whale tracking tools.

## Install

```bash
pnpm add @motosan-whale/nansen
```

## Usage

```typescript
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