Flows

tgm/flows

post

Token holder statistics tracking smart money holders, balances, and cost basis for unichain

Authorizations

Body

Responses

200

Successful response

application/json

400

Bad request

application/json

401

Authentication error

application/json

403

Forbidden - Subscription tier required

application/json

500

Internal server error

application/json

post

HTTPcURLJavaScriptPython

POST /api/beta/tgm/flows HTTP/1.1
Host: api.nansen.ai
apiKey: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 213

{
  "parameters": {
    "chain": "ethereum",
    "tokenAddress": "0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48",
    "date": {
      "from": "2025-05-01",
      "to": "2025-05-03"
    },
    "label": "top_100_holders"
  },
  "pagination": {
    "page": 1,
    "recordsPerPage": 100
  }
}

[
  {
    "blockDate": "text",
    "priceUsd": 1,
    "totalBalance": "text",
    "totalBalanceUsd": "text",
    "totalHolders": "text",
    "totalInflows": "text",
    "totalOutflows": "text",
    "totalInflowsDex": "text",
    "totalOutflowsDex": "text",
    "totalInflowsCex": "text",
    "totalOutflowsCex": "text"
  }
]

Using /flows Endpoint

The /flows endpoint allows you to analyze historical inflows and outflows of token holdings across specific wallet labels (e.g., Smart Money, Whales, Public Figures, etc.) on supported blockchains. This enables powerful workflows to investigate token accumulation or distribution trends by high-signal wallet groups over time.

This guide walks through how to use the endpoint in a workflow to explore Smart Money behavior for a given token on a given chain.

Usecase 1: Track Smart Money Accumulation Trends

This workflow helps you:

• Identify what tokens Smart Money is holding (e.g., via /holdings or /inflows)

• Investigate how inflows/outflows of Smart Money have evolved over time

• Combine historical activity with price trends for better decision-making

Step by Step Guide:

1. Start with /holdings endpoint to identify what tokens Smart Money is holding.

2. Pick a token of interest based on value and activity patterns.

3. Use the /flows endpoint with the token address and smart_money label to view inflow/outflow trends.

4. Specify timeframe (e.g., last 30 days) and examine how Smart Money behavior is evolving.

Usecase 2: Monitor Exchange Flows

This workflow helps you:

• Track how much of a token is being sent to or from exchange wallets

• Spot accumulation or distribution trends by observing net exchange flow

• Correlate token price movement with CEX behavior patterns

Step by Step Guide:

1. Identify the token of interest (e.g., USDC, ETH, SOL).

2. Choose the chain where it is active.

3. Use label: "exchange" to track exchange wallets.

4. Analyze net flows:

   • High inflow = Possible sell pressure

   • High outflow = Possible accumulation

5. Correlate flow data with price action or events (e.g., listings, unlocks, news).