{
  "id": "surf.hyperliquid.trades.aggregate",
  "object": "tool",
  "name": "Closed Trades Aggregate",
  "summary": "Returns a wallet's closed trades rolled up server-side into one row per group — so the P&L calendar, per-symbol / direction / size attribution, and the realized equity curve are one call each instead of paging the whole trade history.",
  "description": "Returns a wallet's closed trades rolled up server-side into one row per group — so the P&L calendar, per-symbol / direction / size attribution, and the realized equity curve are one call each instead of paging the whole trade history. group_by: day (UTC calendar day — the calendar and equity-curve source), symbol (per market), direction (long vs short), size_bucket (notional-USD tiers: <1k, 1k-10k, 10k-100k, 100k-1m, 1m+), or hold_bucket (holding-time tiers: <5m, 5m-1h, 1h-1d, 1d-1w, 1w+). Tiers with no trades are omitted — render the full ladder client-side and zero-fill. One dimension per call. Per group: trade_count, gross_pnl, net_pnl (funding-excluded — gross − fees, matching /trades and /performance), fees, funding_pnl (live tail only), win_rate, volume_usd (notional), avg_win, avg_loss. from/to (Unix seconds or a date) bound close_time; omit for full history. Totals reconcile to /trades and /performance — all three read the same episodes universe (warehouse ≤ watermark plus the live gap-fill past it) through one shared watermark; only the live gap-fill contributes trades past the watermark, and funding_pnl is populated on that tail alone. dex scopes to one market (omit to aggregate across markets). For group_by=day, fill_gaps=true emits zero rows for no-trade days (a dense calendar; requires from). Not paginated — every group in the window is returned in one response.\n\nRaw surf#hyperliquid/trades/aggregate endpoint: input is { body, queryParams, pathParams } as the provider documents them (https://docs.asksurf.ai/data-api/hyperliquid/trades-aggregate).",
  "category": "lookup",
  "hosted_by": "Surf",
  "runtime": "partner",
  "side_effects": false,
  "status": "live",
  "credits": 0,
  "price": null,
  "providers": [
    {
      "id": "surf",
      "name": "Surf",
      "price": null,
      "own_key_only": true
    }
  ],
  "mcp_name": "surf_hyperliquid_trades_aggregate",
  "input_schema": {
    "type": "object",
    "properties": {
      "queryParams": {
        "type": "object",
        "properties": {
          "address": {
            "type": "string",
            "minLength": 1,
            "description": "Wallet address: a 0x EVM address or an ENS name (e.g. vitalik.eth). Solana addresses are not supported."
          },
          "group_by": {
            "default": "day",
            "type": "string",
            "enum": [
              "day",
              "symbol",
              "direction",
              "size_bucket",
              "hold_bucket"
            ],
            "description": "Dimension to roll up by. day = UTC calendar day (the P&L calendar / equity-curve source); symbol = per market; direction = long vs short; size_bucket = notional-USD tiers; hold_bucket = holding-time tiers. Defaults to \"day\"."
          },
          "from": {
            "type": "string",
            "minLength": 1,
            "description": "Window start, bounds close_time: Unix seconds, an ISO datetime (2026-03-01T12:00:00Z), or a bare date (= midnight UTC). Omit for full history. Example: 2026-03-01."
          },
          "to": {
            "type": "string",
            "minLength": 1,
            "description": "Window end, inclusive, bounds close_time: 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-31."
          },
          "dex": {
            "type": "string",
            "enum": [
              "main_dex",
              "xyz",
              "flx",
              "vntl",
              "hyna",
              "km",
              "abcd",
              "cash",
              "para",
              "mkts"
            ],
            "description": "Market scope: main_dex for the native market only, omit to aggregate across ALL markets, or a builder market — one of: xyz, flx, vntl, hyna, km, abcd, cash, para, mkts. NOTE: the omit default differs from /leaderboard, where omitting dex means the native market only."
          },
          "fill_gaps": {
            "default": false,
            "type": "boolean",
            "description": "group_by=day only: emit a zero row for every no-trade UTC day in the window so the calendar is dense. Requires from (a bounded window); ignored for other group_by values. Defaults to false."
          }
        },
        "required": [
          "address"
        ],
        "additionalProperties": false
      }
    },
    "required": [
      "queryParams"
    ],
    "additionalProperties": false
  },
  "kind": "endpoint"
}