# userPnlSummary

Returns aggregate realized-PnL metrics for a user, derived from their completed (fully closed) positions. Includes total net PnL, win/loss rates, volume traded, fees, funding PnL, account age, traded pairs, and a heuristic "human score" (0–100, higher = more likely human, lower = more likely an algorithmic trader).

`startTime` and `endTime` are optional and let you scope the metrics to a specific window (filtered on the position's `close_time`).

`dex` is optional. Omit for aggregate across every perp DEX. Set to `"main_dex"` for the native Hyperliquid dex, or to a HIP-3 dex name (e.g. `"xyz"`) to scope to that dex. When the filter is set, `tradedPairs` is scoped to the dex; `accountAgeDays` is always lifetime by design.

**note: data used to compute the leaderboard is starting from 1st of aug 2025**

## POST Request

<table><thead><tr><th width="161.9998779296875">Field</th><th width="119">Type</th><th>Description</th></tr></thead><tbody><tr><td><code>type</code></td><td>string</td><td>Must be <code>"userPnlSummary"</code></td></tr><tr><td><code>user</code></td><td>string</td><td>Ethereum address (0x-prefixed, 42 characters)</td></tr><tr><td><code>startTime</code></td><td>int</td><td>Start time in ms, filters on <code>close_time</code> (optional)</td></tr><tr><td><code>endTime</code></td><td>int</td><td>End time in ms, filters on <code>close_time</code> (optional)</td></tr><tr><td><code>dex</code></td><td>string</td><td>Scope to a single perp DEX. <code>"main_dex"</code> for the native Hyperliquid dex, or a HIP-3 dex name (e.g. <code>"xyz"</code>). Omit for all dexes (optional)</td></tr></tbody></table>

{% tabs %}
{% tab title="cURL" %}

```bash
curl -X POST https://api.hydromancer.xyz/info \
  -H "Authorization: Bearer $HYDROMANCER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "userPnlSummary",
    "user": "0x0000000000000000000000000000000000000000"
  }'
```

{% endtab %}

{% tab title="Python" %}

```python
import requests
import os

response = requests.post(
    'https://api.hydromancer.xyz/info',
    json={
        'type': 'userPnlSummary',
        'user': '0x0000000000000000000000000000000000000000'
    },
    headers={
        'Authorization': f'Bearer {os.environ.get("HYDROMANCER_API_KEY")}',
        'Content-Type': 'application/json'
    }
)

print(response.json())
```

{% endtab %}

{% tab title="Javascript" %}

```javascript
import axios from 'axios';

try {
    const response = await axios.post('https://api.hydromancer.xyz/info', {
        type: 'userPnlSummary',
        user: '0x0000000000000000000000000000000000000000'
    }, {
        headers: {
            'Authorization': `Bearer ${process.env.HYDROMANCER_API_KEY}`,
            'Content-Type': 'application/json'
        }
    });

    console.log(response.data);
} catch (error) {
    console.error('Error:', error.message);
}
```

{% endtab %}
{% endtabs %}

***

## Response Fields

| Field            | Type      | Description                                                                                                                                                                        |
| ---------------- | --------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `user`           | string    | Ethereum address (echoed from the request)                                                                                                                                         |
| `totalPnl`       | string    | Sum of net PnL across all completed trades in the window. Net PnL is `gross_pnl - fees + funding_pnl`                                                                              |
| `winRate`        | float     | Fraction of trades with `net_pnl > 0`, rounded to 4 decimals (0–1)                                                                                                                 |
| `lossRate`       | float     | Fraction of trades with `net_pnl <= 0`, rounded to 4 decimals (0–1)                                                                                                                |
| `totalTrades`    | int       | Number of completed trades in the window                                                                                                                                           |
| `volumeTraded`   | string    | Sum of `\|px × sz\|` across all of the user's fills in the window (notional traded)                                                                                                |
| `totalFees`      | string    | Sum of fees paid across completed trades                                                                                                                                           |
| `totalFunding`   | string    | Sum of cumulative funding PnL across completed trades (positive = received, negative = paid). Already included in `totalPnl`                                                       |
| `daysActive`     | int       | Number of distinct UTC days on which the user had any fill in the window                                                                                                           |
| `accountAgeDays` | int?      | Days between the user's earliest known fill and now. `null` if the user has never had a fill on record                                                                             |
| `tradedPairs`    | string\[] | Distinct coin symbols the user has ever filled on (lifetime)                                                                                                                       |
| `humanScore`     | int       | Heuristic 0–100 score, higher = more likely a human trader. Combines average fills per trade, average distinct trading hours per active day, and the ratio of maker to taker fills |

<details>

<summary>Response</summary>

```json
{
  "user": "0x0000000000000000000000000000000000000000",
  "totalPnl": "12345.67",
  "winRate": 0.6234,
  "lossRate": 0.3766,
  "totalTrades": 412,
  "volumeTraded": "8421000.00",
  "totalFees": "1684.20",
  "totalFunding": "-23.45",
  "daysActive": 87,
  "accountAgeDays": 312,
  "tradedPairs": ["BTC", "ETH", "SOL", "HYPE"],
  "humanScore": 95
}
```

</details>


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.hydromancer.xyz/readme/rest-api/user-performance/userpnlsummary.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.