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

# Understanding Vault Performance Metrics

> Learn how perf3, perf6, perf12, perfTot, MDD, and botOverMarket are calculated, and how to query historical performance data and your personal gains.

Every vault exposes a set of pre-computed performance metrics that help you evaluate a strategy's track record. These figures are updated automatically at regular intervals based on the vault's closed trade history, with leverage applied for perp vaults. Understanding how each metric is derived helps you compare vaults accurately and interpret what the numbers mean for your position.

## Performance fields explained

<ResponseField name="perf3" type="decimal">
  **3-month performance (%)** — the compounded return of all trades that opened within the last 3 months, with the vault's `leverage` multiplier applied. A value of `15.5` means the strategy returned 15.5% over that period.
</ResponseField>

<ResponseField name="perf6" type="decimal">
  **6-month performance (%)** — same calculation over the last 6 months.
</ResponseField>

<ResponseField name="perf12" type="decimal">
  **12-month performance (%)** — same calculation over the last 12 months.
</ResponseField>

<ResponseField name="perfTot" type="decimal">
  **Total performance (%)** — the average monthly performance across all months for which data exists. This gives a smoothed long-run view of the strategy's typical monthly returns.
</ResponseField>

<ResponseField name="mdd" type="decimal">
  **Maximum drawdown (%)** — the largest peak-to-trough decline in the vault's cumulative return since inception. Calculated by walking through all closed trades in chronological order, tracking a running equity curve, and recording the deepest percentage drop from any historical peak. A value of `-12.3` means the worst decline from a peak was 12.3%.
</ResponseField>

<ResponseField name="botOverMarket" type="decimal">
  **Bot vs market (%)** — computed as `perf12` minus the 12-month return of `currency2` as fetched from CoinGecko. A positive value means the vault outperformed simply buying and holding the traded asset over the same period.
</ResponseField>

<Note>
  For SuperVaults, all performance fields are the average of the corresponding field across all connected member vaults, recomputed automatically at regular intervals.
</Note>

## Querying time-series performance data

To power a performance chart for a specific vault, use the performance data endpoint:

```http theme={null}
GET /vaults/performance-data/{vaultId}/{filter}
```

<ParamField path="vaultId" type="string" required>
  The vault ID. If the ID begins with `supervault`, the backend aggregates trades from all connected member vaults.
</ParamField>

<ParamField path="filter" type="string" required>
  Time window for the chart. Accepted values:

  | Value  | Period                |
  | ------ | --------------------- |
  | `1M`   | 30 days               |
  | `3M`   | 90 days               |
  | `6M`   | 180 days              |
  | `Year` | 365 days              |
  | `All`  | All available history |
</ParamField>

The response is an array of data points in reverse chronological order. Each point contains:

| Field         | Description                                              |
| ------------- | -------------------------------------------------------- |
| `id`          | Start timestamp of the data window                       |
| `vaultId`     | The vault ID you queried                                 |
| `performance` | Percentage return for that window, with leverage applied |

## Querying personal gains

### Your gain for a single vault

```http theme={null}
GET /vaults/total-gain/{vaultId}/{account}
```

Returns your current on-chain balance in the vault minus the net amount you deposited (total deposits minus total withdrawals). A positive value means you have profited; a negative value means you are down relative to your cost basis.

### Your gain across all vaults

```http theme={null}
GET /vaults/total-gain-all/{account}
```

Sums your on-chain balance across every active vault and subtracts your total net deposit across all vaults. This gives a single figure representing your overall gain or loss on the platform.

## Viewing trade history

```http theme={null}
GET /vaults/trades-history/{vaultId}
```

Returns the 50 most recent closed trades for the vault, ordered by `openAt` descending. Each record includes entry price, close price, and the opening and closing transaction hashes.

This data is rendered as a table in the trade history section of the vault detail view.

## Monthly performance breakdown

The vault detail view includes a monthly performance chart showing returns broken down by calendar month. It provides a granular view of seasonality and drawdown periods that the single headline figures do not capture.

## Safety level and risk level

Each vault carries two complementary risk indicators:

* **`safetyLevel`** (integer) — a numeric score. A higher number indicates a safer, more conservative strategy.
* **`riskLevel`** (string) — a human-readable classification assigned to the vault.

<Tip>
  High `perf12` figures are often associated with higher `mdd` values. Always consider the maximum drawdown alongside the headline return when evaluating a vault.
</Tip>