---
title: "Get Perpetual Trade Data"
method: POST
path: "/api/v1/profiler/perp-trades"
tags: ["Profiler"]
---

# Get Perpetual Trade Data

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

Get perpetual trade data for a user. This endpoint provides trade information including trade price, size, side, fees, and other trade details.

**What it helps to answer:**

1. **What are the perpetual trades for a specific user address within a date range?**
2. **What are the trade prices, sizes, and directions for each trade?**
3. **What are the trading fees and closed PnL for each trade?**
4. **What are the order IDs and transaction hashes for trade tracking?**

## Request body

- PerpTradeRequest — Request model for Perp Trades endpoint.
  - `address` string, required — User's Hyperliquid address in 42-character hexadecimal format
  - `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)
  - `filters` PerpTradeFilters — Filters for perp trades endpoint. These filters control which perpetual trades are included in the results based on various trade criteria.
    - `token_symbol` string — Token symbol filter
    - `side` 'Long' | 'Short' — Enum for perp trade position types.
    - `action` 'Open/Add' | 'Close/Reduce' | 'Liquidation' — Enum for perp trade action filters (grouped).
    - `crossed` boolean — Whether the trade was crossed
    - `size` 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)
    - `start_position` 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)
    - `closed_pnl` 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)
    - `fee_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)
    - `fee_token_symbol` string — Fee token filter
    - `oid` 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)
    - `price` 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)
  - `pagination` PaginationRequest — Pagination parameters for API requests.
    - `page` integer — Page number (1-based)
    - `per_page` integer — Number of records per page (max 1000)
  - `order_by` SortOrderPerpTradeSortField[] — Sort order for the trades
    - `field` 'timestamp' | 'size' | 'fee_usd' | 'closed_pnl' | 'price' | 'value_usd', required — Enum for perp trade sort fields.
    - `direction` 'ASC' | 'DESC', required — Enum for sort directions.

## Response `200`

Perpetual trade data for the user

- PerpTradeResponse — Response model for perp trades endpoint.
  - `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
  - `data` PerpTrade[], required — List of perpetual trades
    - `timestamp` string, required — Timestamp of the trade
    - `side` 'Long' | 'Short', required — Enum for perp trade position types.
    - `action` string, required — Action taken (Open, Add, Close, Reduce, etc.)
    - `block_number` integer, required — Block number of the trade
    - `token_symbol` string, required — Symbol of the token
    - `price` number, required — Average price of the trade (averaged across fills)
    - `size` number, required — Total size of the trade (sum of all fills)
    - `value_usd` number, required — Total value in USD of the trade
    - `start_position` number, required — Start position of the trade in token units
    - `closed_pnl` number, required — Total closed PnL of the trade (sum of all fills)
    - `crossed` boolean, required — Crossed of the trade
    - `fee_usd` number, required — Total fee in USD of the trade (sum of all fills)
    - `fee_token_symbol` string, required — Fee in token of the trade
    - `transaction_hash` string, required — Transaction hash of the trade
    - `user` string, required — User of the trade
    - `oid` integer, required — Order ID of the trade

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