---
title: "Get \"Token God Mode\" (TGM) flows data"
method: POST
path: "/api/v1/tgm/flows"
tags: ["Token God Mode"]
---

# Get "Token God Mode" (TGM) flows data

`POST /api/v1/tgm/flows`

Analyze aggregated token flows by holder category over time. Shows hourly snapshots of balances, inflows, and outflows for specific holder groups: smart money, public figures, whales, and exchanges.

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

## Request body

- TGMFlowsRequest — 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.
  - `chain` 'arbitrum' | 'avalanche' | 'base' | 'bnb' | 'ethereum' | 'hyperevm' | 'hyperliquid' | 'injective' | 'iotaevm' | 'linea' | 'mantle' | 'mantra' | 'monad' | 'near' | 'optimism' | 'plasma' | 'polygon' | 'robinhood' | 'sei' | 'solana' | 'sonic' | 'starknet' | 'sui' | 'ton' | 'tron', required — Chains supported for the TGM flows endpoint.
  - `token_address` string, required — Token address
  - `date` DateRange, required — Date range model matching the API schema.
    - `from` string — Start date in ISO 8601 format (e.g., 2025-01-01T00:00:00Z or 2025-01-01)
    - `to` string — End date in ISO 8601 format (e.g., 2025-01-31T23:59:59Z or 2025-01-31)
  - `label` 'whale' | 'public_figure' | 'smart_money' | 'top_100_holders' | 'exchange' — TGM flow label types.
  - `pagination` PaginationRequest — Pagination parameters for API requests.
    - `page` integer — Page number (1-based)
    - `per_page` integer — Number of records per page (max 1000)
  - `filters` TGMFlowsFilters — Filters for TGM flows endpoint. These filters control which data points are included in the flows analysis.
    - `price_usd` NumericRangeFilter — Filter for numeric values (floats) with optional min/max bounds. Use for prices, volumes, ratios, and other decimal values. - Values between -10.5 and 100.75
      - `min` number — Minimum value (inclusive)
      - `max` number — Maximum value (inclusive)
    - `token_amount` NumericRangeFilter — Filter for numeric values (floats) with optional min/max bounds. Use for prices, volumes, ratios, and other decimal values. - Values between -10.5 and 100.75
      - `min` number — Minimum value (inclusive)
      - `max` number — Maximum value (inclusive)
    - `value_usd` NumericRangeFilter — Filter for numeric values (floats) with optional min/max bounds. Use for prices, volumes, ratios, and other decimal values. - Values between -10.5 and 100.75
      - `min` number — Minimum value (inclusive)
      - `max` number — Maximum value (inclusive)
    - `holders_count` IntegerRangeFilter — Filter for integer values with optional min/max bounds. Use for counts, numbers of items, and other whole number values. - Values between 5 and 100
      - `min` integer — Minimum value (inclusive)
      - `max` integer — Maximum value (inclusive)
    - `total_inflows_count` IntegerRangeFilter — Filter for integer values with optional min/max bounds. Use for counts, numbers of items, and other whole number values. - Values between 5 and 100
      - `min` integer — Minimum value (inclusive)
      - `max` integer — Maximum value (inclusive)
    - `total_outflows_count` IntegerRangeFilter — Filter for integer values with optional min/max bounds. Use for counts, numbers of items, and other whole number values. - Values between 5 and 100
      - `min` integer — Minimum value (inclusive)
      - `max` integer — Maximum value (inclusive)
  - `order_by` SortOrderTGMFlowsSortField[] — 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
    - `field` 'date' | 'price_usd' | 'token_amount' | 'value_usd' | 'holders_count' | 'total_inflows_count' | 'total_outflows_count' | 'total_inflows_dex' | 'total_outflows_dex' | 'total_inflows_cex' | 'total_outflows_cex', required — Enum for sortable fields in TGM flows.
    - `direction` 'ASC' | 'DESC', required — Enum for sort directions.

## Response `200`

TGM flows data

- TGMFlowsResponse — Response model for TGM flows endpoint. Contains a list of flow records with pagination and metadata.
  - `data` TGMFlows[], required — List of TGM flow records
    - `date` string, required — Block date of the flow data point
    - `price_usd` number — Daily median token price in USD. For the current day, uses the latest spot price.
    - `token_amount` number — Total token amount
    - `value_usd` number — Total token value in USD
    - `holders_count` integer — Number of token holders
    - `total_inflows_count` number — Total inflows
    - `total_outflows_count` number — Total outflows
    - `total_inflows_dex` number — Total DEX inflows (token amount). Only populated when label=exchange, null otherwise.
    - `total_outflows_dex` number — Total DEX outflows (token amount). Only populated when label=exchange, null otherwise.
    - `total_inflows_cex` number — Total CEX inflows (token amount). Only populated when label=exchange, null otherwise.
    - `total_outflows_cex` number — Total CEX outflows (token amount). Only populated when label=exchange, null otherwise.
  - `pagination` PaginationInfo, required — Pagination information for API responses.
    - `page` integer — Current page number
    - `per_page` integer — Number of records per page
    - `is_last_page` boolean — Whether this is the last page
  - `warnings` string[] — Optional warnings about the query results. For example, when the DEX/CEX flow fields are null because a non-exchange label was requested.

## Other responses

- `400` — Bad Request - Invalid request parameters or malformed request
- `401` — Authentication error - No API key found in request
- `402` — Payment Required - This endpoint supports pay-per-request via x402 and MPP. x402 responses advertise payment options in `Payment-Required`; MPP responses advertise a fresh `WWW-Authenticate: Payment ...` challenge. Successful MPP responses may include `Payment-Receipt`.
- `403` — Forbidden - User does not have required subscription tier or has exceeded credit limit
- `404` — Not Found - The requested resource was not found
- `422` — Validation error - Invalid request parameters
- `429` — Too Many Requests - Rate limit exceeded
- `500` — Internal Server Error - An unexpected error occurred

---

[API](https://skmtc.net/nansen/apis/nansen-api.md) · [All operations](https://skmtc.net/nansen/apis/nansen-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/nansen/nansen-api/revisions/02a4d2e7d827/schema)