Closed Trades

GET/gateway/v1/hyperliquid/trades

Returns a wallet's closed round-trip trades — one row per open→close position lifecycle, with realized per-trade P&L (gross, net = gross − fees, fees, and `funding_pnl` as a separate field that net EXCLUDES), entry/exit price, size, and hold time. Newest close first. This is the journal / calendar / attribution source; for fill-level executions use `/hyperliquid/fills` instead.

Returns EVERY closed trade in the window — it does NOT filter by symbol or direction (a `symbol`/`direction` query param is ignored, not applied); for per-symbol / per-direction rollups use `/hyperliquid/trades/aggregate`, or `/hyperliquid/fills` for symbol-scoped fills. `funding_pnl` is 0 for warehouse rows and populated only on the live tail, so a funding-inclusive total is incomplete before the watermark.

Cursor-paged over the full history (warehouse + a live gap-fill for the most recent days): follow `meta.next_cursor` to page back. The cursor is a complete continuation token (it encodes the window + position), so pass it with only `address` and `limit` — combining it with `from`/`to` is rejected. `from`/`to` (Unix seconds or a date) bound the window on the first page. A wallet with an extremely large live (post-warehouse) trade history may require a `from`/`to` window.

Query Parameters

addressstringrequired

Wallet address: a 0x EVM address or an ENS name (e.g. vitalik.eth). Solana addresses are not supported.

symbolstring

NOT SUPPORTED on /trades — returns 400 if set. Per-symbol slicing lives on /trades/aggregate (group_by=symbol) or client-side.

directionenum<string>

NOT SUPPORTED on /trades — returns 400 if set. Per-direction slicing lives on /trades/aggregate (group_by=direction) or client-side.

Available options:longshort

dexstring

NOT SUPPORTED on /trades — returns 400 if set. Market scoping lives on /trades/aggregate (dex=...).

fromstring

Window start: Unix seconds, an ISO datetime (2026-03-01T12:00:00Z), or a bare date (= midnight UTC). Omit for the full history.

Example: 2026-03-01

tostring

Window end, inclusive: Unix seconds, an ISO datetime, or a bare date — a bare date means the END of that UTC day, so from=X&to=X covers the whole day X. Defaults to now.

Example: 2026-03-01

cursorstring

Opaque continuation token from a previous response's meta.next_cursor. It encodes the window, position, and address, so pass it with only address + limit — and only with the address it was issued for. Tokens are single-use opaque values: identical requests mint different tokens that decode to the same position.

limitinteger

Page size (1-100).

Closed Trades

const options = {method: 'GET'};

fetch('https://api.asksurf.ai/gateway/v1/hyperliquid/trades?from=2026-03-01&to=2026-03-01', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

{
  "$schema": "https://example.com/schemas/CursorDataResponseHyperliquidEpisode.json",
  "data": [
    {
      "close_time": 123,
      "direction": "<string>",
      "entry_px": 123,
      "episode_id": "<string>",
      "exit_px": 123,
      "fees": 123,
      "funding_pnl": 123,
      "gross_pnl": 123,
      "hold_seconds": 123,
      "is_win": true,
      "net_pnl": 123,
      "notional_usd": 123,
      "open_time": 123,
      "opened_sz": 123,
      "source": "<string>",
      "symbol": "<string>"
    }
  ],
  "meta": {
    "cached": true,
    "credits_used": 123,
    "empty_reason": "<string>",
    "has_more": true,
    "limit": 123,
    "next_cursor": "<string>",
    "watermark": 123
  }
}