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

# Get "Token God Mode" (TGM) perp trades data

`POST /api/v1/tgm/perp-trades`

Retrieve perpetual trade data for a specific token on Hyperliquid. Shows individual trades with detailed information including trader address, trade side (Long/Short), action type (Add/Reduce/Open/Close), order type (Market/Limit), and trade metrics.

**Key Features:**
- Hyperliquid perpetual contracts only
- Smart money filtering capabilities
- Detailed trade breakdown with parsed action fields
- Support for both Long and Short position trading
- Market and Limit order types

**Request Parameters:**
- `token_symbol`: Token symbol to fetch trades for (e.g., "BTC", "ETH")
- `date`: Date range for the trades
- `filters`: Additional filters for side, action, order_type, etc.
- `pagination`: Page and per_page parameters

## Request body

- TGMPerpTradesRequest — Request model for TGM perp trades endpoint. This endpoint provides perp trades data for a specific token.
  - `token_symbol` string, required — Token symbol
  - `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)
  - `pagination` PaginationRequest — Pagination parameters for API requests.
    - `page` integer — Page number (1-based)
    - `per_page` integer — Number of records per page (max 1000)
  - `filters` TGMPerpTradesFilters — Filters for TGM perp trades endpoint. These filters control which perp trades are included in the results.
    - `trader_address` union — Trader address filter
      - string
      - string[]
    - `trader_address_label` union — Trader label filter
      - string
      - string[]
    - `side` union — Position side filter (Long or Short)
      - 'Long' | 'Short' — Shared enum for position side direction.
      - PositionSide[]
    - `action` union — Action filter with combined buy/sell direction (e.g., 'Buy - Add Long', 'Sell - Reduce Long')
      - 'Buy - Add Long' | 'Buy - Reduce Short' | 'Buy - Open Long' | 'Buy - Close Short' | 'Sell - Add Short' | 'Sell - Reduce Long' | 'Sell - Open Short' | 'Sell - Close Long' — Shared enum for perpetual trade action types (combined buy/sell with position actions).
      - PerpActionType[]
    - `order_type` union — Order type filter (MARKET or LIMIT)
      - 'MARKET' | 'LIMIT' — Order type.
      - OrderType[]
    - `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)
    - `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)
    - `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)
    - `include_smart_money_labels` SmartMoneyFilterType[] — Include smart money labels
    - `exclude_smart_money_labels` SmartMoneyFilterType[] — Exclude smart money labels
  - `order_by` SortOrderTGMPerpTradesSortField[] — Custom sort order to override the endpoint's default ordering. Examples: - [{"field": "block_timestamp", "direction": "DESC"}] - Sort by timestamp descending - [{"field": "value_usd", "direction": "DESC"}] - Sort by trade value descending Default: block_timestamp DESC, transaction_hash ASC, trader_address ASC (ensures stable pagination and prevents duplicate rows)
    - `field` 'block_timestamp' | 'token_amount' | 'value_usd' | 'transaction_hash' | 'trader_address', required — Enum for sortable fields in TGM perp trades.
    - `direction` 'ASC' | 'DESC', required — Enum for sort directions.

## Response `200`

TGM perp trades data

- TGMPerpTradesResponse — Response model for TGM perp trades endpoint. Contains a list of perp trade records with pagination and metadata.
  - `data` TGMPerpTrade[], required — List of TGM perp trade records
    - `trader_address_label` string — The label associated with the trader
    - `trader_address` string, required — The trader's address
    - `token_symbol` string — The symbol of the token
    - `side` 'Long' | 'Short' — Shared enum for position side direction.
    - `action` string, required — The action taken by the trader (Add, Reduce, Open, Close)
    - `token_amount` number — The amount of the specified token traded
    - `price_usd` number — Average fill price in USD across all fills in the trade, from exchange data.
    - `value_usd` number — The value in USD
    - `type` 'MARKET' | 'LIMIT', required — Order type.
    - `block_timestamp` string, required — The block timestamp for the transaction
    - `transaction_hash` string, required — A representative transaction hash for this trade. Note: A single row may aggregate multiple fills that occurred at the same timestamp. If the trader had fills across multiple transactions at the exact same millisecond, only one transaction_hash is shown. The token_amount and value_usd reflect the total across all fills.
  - `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

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