Ctrlk
x-twitteryoutube
For the complete documentation index, see llms.txt. This page is also available as Markdown.

Flows

This endpoint does not support native tokens on any chain. Use a contract token address. See Native Tokens for endpoint-specific coverage.

Data Freshness & Historical Coverage

For data freshness and historical coverage, see Data Coverage by Chain; this endpoint follows it.

Get "Token God Mode" (TGM) flows data

post

Analyze aggregated token flows by holder category over time. Shows hourly snapshots for ranges of seven days or less and daily snapshots for longer ranges.

date and bucket_end are RFC 3339 UTC timestamps for the inclusive start and exclusive end of each aggregation bucket. The request date.to value is an inclusive cutoff. is_complete is false when that upper cutoff truncates a bucket or the bucket is still live. On Hyperliquid it is also false when date.from truncates the first bucket; on other chains the lower cutoff is aligned to the bucket start, so the full first bucket is returned. This flag describes request-window coverage, not whether the underlying data is final or will never be revised. Consumers should omit or visibly mark incomplete buckets in normal historical views.

Note: the DEX/CEX breakdown fields (total_inflows_dex, total_outflows_dex, total_inflows_cex, total_outflows_cex) are only populated when label=exchange and are null for all other labels; a warnings entry is included in the response in that case. For net flow per holder segment (e.g. smart money), use the Flow Intelligence endpoint (POST /api/v1/tgm/flow-intelligence).

Authorizations
apikeystringRequired

API key for authentication

Body

Request model for TGM flows endpoint.

This endpoint provides comprehensive token flow analytics showing inflow and outflow patterns from various holder segments including Exchanges, Smart Money addresses, Public Figures, and Whales with time-based statistics and trends.

chainstring · enumRequired

Blockchain chain

Example: solanaPossible values:
token_addressstringRequired

Token address

Example: 2zMMhcVQEXDtdE6vsFS7S7D5oUodfJHE8vd1gnBouauv
labelstring · enumOptional

Label type for filtering flows

Default: top_100_holdersExample: smart_moneyPossible values:
filtersany ofOptional

Additional filters to apply to the query.

Example: {"price_usd":{"max":1000,"min":0.01},"value_usd":{"min":10000}}
order_byany ofOptional

Custom sort order to override the endpoint's default ordering.

Examples:

  • [{"field": "date", "direction": "DESC"}] - Sort by date descending (most recent first)
  • [{"field": "total_inflows_usd", "direction": "ASC"}] - Sort by total inflows ascending
  • [{"field": "total_outflows_usd", "direction": "DESC"}] - Sort by total outflows descending
Responses
200

TGM flows data

application/json
post/api/v1/tgm/flows
POST /api/v1/tgm/flows HTTP/1.1
Host: api.nansen.ai
apikey: YOUR_API_KEY
Content-Type: application/json
Accept: */*
Content-Length: 330

{
  "chain": "solana",
  "token_address": "2zMMhcVQEXDtdE6vsFS7S7D5oUodfJHE8vd1gnBouauv",
  "date": {
    "from": "2025-05-01T00:00:00Z",
    "to": "2025-05-03T23:59:59Z"
  },
  "label": "smart_money",
  "pagination": {
    "page": 1,
    "per_page": 10
  },
  "filters": {
    "price_usd": {
      "max": 1000,
      "min": 0.01
    },
    "value_usd": {
      "min": 10000
    }
  },
  "order_by": [
    {
      "field": "date",
      "direction": "ASC"
    }
  ]
}
{
  "data": [
    {
      "date": "text",
      "bucket_end": "text",
      "is_complete": true,
      "price_usd": 1,
      "token_amount": 1,
      "value_usd": 1,
      "holders_count": 1,
      "total_inflows_count": 1,
      "total_outflows_count": 1,
      "total_inflows_dex": 1,
      "total_outflows_dex": 1,
      "total_inflows_cex": 1,
      "total_outflows_cex": 1
    }
  ],
  "pagination": {
    "page": 1,
    "per_page": 10,
    "is_last_page": true
  },
  "warnings": [
    "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 a supported contract token of interest (for example, USDC). Native assets such as ETH and SOL are not supported by this endpoint.

  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).

PreviousHolders
NextPosition Intelligence

Last updated

Was this helpful?