> ## Documentation Index
> Fetch the complete documentation index at: https://docs.hypedexer.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Social Trading

> Per-trader equity curve, PnL calendar, performance stats, account leverage and top trades — everything needed to build a copy-trading or leaderboard product.

Everything below works for **any Hyperliquid address** — no opt-in, no registration from the trader. Five endpoints cover a full trader profile page.

<CardGroup cols={2}>
  <Card title="Equity chart" icon="chart-area" href="/api-reference/social-trading/equity-history">
    Account value over time with cash, open notional, unrealized PnL and leverage at each point.
  </Card>

  <Card title="PnL calendar" icon="calendar" href="/api-reference/social-trading/pnl-calendar">
    Daily realized PnL, fees, funding and net result — the data behind a calendar heatmap.
  </Card>

  <Card title="Performance" icon="chart-simple" href="/api-reference/social-trading/user-performance">
    Win rate, PnL, trade count, volume, average holding time, long/short ratio, max drawdown.
  </Card>

  <Card title="Account & leverage" icon="scale-balanced" href="/api-reference/social-trading/account-state-and-leverage">
    Current equity, account leverage and every open position with its own leverage.
  </Card>
</CardGroup>

## Building a trader profile

A typical profile page maps one-to-one onto these calls:

| Section of your UI                                         | Endpoint                                                              |
| ---------------------------------------------------------- | --------------------------------------------------------------------- |
| Equity chart, with a PnL / calendar toggle                 | `GET /users/{user}/equity-history` + `GET /users/{user}/pnl-calendar` |
| Stat row — win rate, PnL, trades, volume, avg holding time | `GET /users/{user}/performance?window=7d`                             |
| Current leverage badge                                     | `GET /users/{user}/account` → `account_leverage`                      |
| Top 5 trades table                                         | `GET /users/{user}/top-trades?limit=5`                                |

All responses are wrapped in `{ success, message, data, execution_time_ms }`. Amounts are USDC, sizes are in the asset's own unit, timestamps are ISO-8601 UTC. Addresses come back lower-cased; an invalid address returns `400`.

## Quick start

<CodeGroup>
  ```bash Performance theme={null}
  curl -s "https://api.hypedexer.com/users/0x0000000000bdc2fd416def2d8688069052eb0f87/performance?window=7d" \
    -H "X-API-Key: $HYPEDEXER_API_KEY"
  ```

  ```bash Equity chart theme={null}
  curl -s "https://api.hypedexer.com/users/0x0000000000bdc2fd416def2d8688069052eb0f87/equity-history?window=7d&interval=1h" \
    -H "X-API-Key: $HYPEDEXER_API_KEY"
  ```

  ```bash PnL calendar theme={null}
  curl -s "https://api.hypedexer.com/users/0x0000000000bdc2fd416def2d8688069052eb0f87/pnl-calendar?window=30d" \
    -H "X-API-Key: $HYPEDEXER_API_KEY"
  ```

  ```bash Account & leverage theme={null}
  curl -s "https://api.hypedexer.com/users/0x0000000000bdc2fd416def2d8688069052eb0f87/account" \
    -H "X-API-Key: $HYPEDEXER_API_KEY"
  ```

  ```bash Top trades theme={null}
  curl -s "https://api.hypedexer.com/users/0x0000000000bdc2fd416def2d8688069052eb0f87/top-trades?limit=5&window=all&sort=pnl" \
    -H "X-API-Key: $HYPEDEXER_API_KEY"
  ```
</CodeGroup>

## Where the numbers come from

Two different sources back these endpoints, and the distinction explains every coverage rule below.

**Round-trip trades** are reconstructed from fills — entry to exit, with realized PnL, duration, fees and funding. They drive `/performance` and `/top-trades`, and are available from **10 September 2025**.

**Account snapshots** are read hourly from the on-chain clearinghouse state on our own full nodes. They drive `/equity-history`, `/account`, the `equity_close` column of the calendar and the leverage on each trade. They are available from **5 September 2026** and accumulate from there.

<Note>
  `account_value` is the **perp** account — the same figure Hyperliquid returns in `clearinghouseState.marginSummary.accountValue`. Spot balances and HIP-3 builder-dex positions are not included yet.
</Note>

### Reading a zero

A trader who moved funds to spot, withdrew, or simply closed everything has an empty perp account. Rather than hiding those moments, the API states them:

* `/account` returns `account_value: 0`, `perp_account_empty: true` and `last_nonempty_snapshot`
* `/equity-history` fills those hours with a `0` point carrying `perp_account_empty: true`

That is a real zero, not missing data — worth handling explicitly if your chart interpolates gaps.

### Leverage

<ResponseField name="leverage_type" type="string">
  `cross` or `isolated` when the trader set it. `default` means they never configured leverage for that asset — Hyperliquid then applies `min(20, maxLeverage)`, and that resolved value is what `leverage` returns.
</ResponseField>

<ResponseField name="leverage on closed trades" type="integer | null">
  Taken from the first hourly snapshot captured while the position was open. Trades closed before **6 September 2026** predate snapshot coverage and return `null`.
</ResponseField>

### Two kinds of drawdown

`/performance` returns both, because they answer different questions:

* `max_drawdown` — measured on the cumulative **realized-PnL curve** of closed trades. Always available.
* `equity_max_drawdown_usd` / `equity_max_drawdown_pct` — measured on **real account value**, which includes unrealized PnL and deposits. Requires snapshot coverage in the window; `equity_snapshots` tells you how many points backed the figure.

## Freshness

Trades and the PnL calendar update within seconds of on-chain execution. Equity, positions and leverage come from hourly snapshots — every response carries an `as_of` (or `points[].time`) with the exact snapshot time, so you can display it rather than implying live data.

<Info>
  Building a copy-trading or leaderboard product and missing a field? Spot balances and HIP-3 dex positions in the equity are the natural next step — [tell us what you need](/guides/for-builders).
</Info>