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

# Legacy and v1

> Compare existing QA-compatible reporting with current v1 accounting.

[Data API overview](/en/developers/data-access) · [Data API patterns](/en/developers/data-api) · [Balances, cost and returns](/en/developers/financial-data)

## Choose the contract

| Topic              | QA-compatible legacy                                                       | Current `/v1`                                                        |
| ------------------ | -------------------------------------------------------------------------- | -------------------------------------------------------------------- |
| Purpose            | Continuity with existing integrations                                      | Confirmed-boundary investment reporting                              |
| Paths              | `/legacy/external/...` and existing compatibility routes                   | `/balances`, `/earnings`, `/apy`                                     |
| Calculation        | Preserved route-specific QA formulas within verified coverage              | Published valuation, flow and cost policy for every supported period |
| Time               | Existing route/grain rules; closed UTC days for holder/PPS                 | Exact instants or local reporting dates; $[start,end)$               |
| Boundaries         | Captured source selections and historical rules                            | Last canonical confirmed block strictly before each boundary         |
| Amounts            | Historical field names/scales, including raw six-decimal USDT `Usd` fields | Native-asset decimal strings with asset identity                     |
| Return calculation | Scope-specific average capital                                             | True TWR using every external-flow valuation                         |
| APY                | Legacy ACT/365 and visibility rules                                        | PPS APY or period annual equivalent, explicitly identified           |
| Evidence gaps      | Explicit `503` for unsupported or incomplete reconstruction                | Explicit unavailable/partial evidence and affected `null` fields     |
| Issued reports     | Preserve the original export                                               | Save query, response, policy and evidence for each report            |

**Key points**

* Existing consumers can keep their legacy contract. New integrations use current v1.
* V1 applies one published policy across supported history. No transition-date parameter is required.
* `/legacy/public/v1/...` preserves a previously published financial payload for consumers that need that compatibility surface.
* Keep original reports and recalculations as separate records; corrections link a new version and reason.

## Current queries

| Need                          | Request                                           |
| ----------------------------- | ------------------------------------------------- |
| Balance at an instant         | `/v1/balances?at=…`                               |
| One period's earnings         | `/v1/earnings?start=…&end=…`                      |
| Daily/monthly report          | Add `interval=day` or `month`; choose `timezone`  |
| Hourly opening/closing values | `/v1/earnings` with `interval=hour`               |
| Observed vault APY            | `/v1/apy?vault=…`                                 |
| Strategy harvest events       | `/v1/harvests?start=…&end=…`                      |
| Reported-asset reconciliation | Add `include=reconciliation` to `/v1/earnings`    |
| Real-time venue estimates     | Add `valuation=estimated_nav` to `/v1/earnings`   |
| Wallet/vault scope            | Add `account` and/or `vault` to balances/earnings |

* Use the [Scalar reference](https://api.superearn.io/v1/docs) for calendars, pagination and payloads.
* Compare the same asset, account scope, time boundaries and balance components when reconciling.

### Legacy harvestReport and totalAssets recognition

Legacy endpoints supported `accountedBy=harvestReport` and `accountedBy=totalAssets` to attribute keeper report gains before 7-day linear PPS degradation. In v1:

* Canonical holder earnings and balance are strictly evaluated under `valuation=pps` (or `valuation=estimated_nav` for pre-harvest venue estimates). Unreleased locked profit is excluded from official PnL because investors cannot redeem it at report time, and subsequent inflows dilute locked profit across shares.
* To inspect strategy harvest gains, query `GET /v1/harvests` for verified report events, net gain, and report-block wallet allocations.
* To reconcile PPS balances against contract total assets including locked profit, add `include=reconciliation` to `/v1/balances` or `/v1/earnings`.

## Average capital

For restored **holder/PPS** calculations:

```text theme={null}
C_bar    = (1 / D) * Sum(C_j * delta_t_j)
r_legacy = E_legacy / C_bar

APR = r_legacy * (Y / D)
g   = 1 + max(r_legacy, -0.999999)
APY = g^(Y / D) - 1
```

| Symbol             | Definition                                                                            |
| ------------------ | ------------------------------------------------------------------------------------- |
| `C_j`, `delta_t_j` | Remaining principal and elapsed seconds in each constant-principal segment            |
| `D`, `Y`           | Period seconds; `Y = 365 * 86,400`                                                    |
| `C_bar`            | Time-weighted remaining principal; `averageCapitalUsd` truncates to raw integer units |
| `E_legacy`         | Closing value minus opening value and legacy-classified net flows                     |

**Calculation rules**

* Use unrounded capital and earnings for rates; monetary output truncates toward zero.
* Require positive capital and duration. Legacy annual rates with magnitude above 50 or nonfinite output return `null`.
* QA-compatible exponentiation retains its original numeric behavior.
* Holder/PPS opening selects state at or before `start`; closing at or before `end - 1 second`; flows use `(start, end - 1 second]`.

The endpoint average and a time-weighted balance measure are:

```text theme={null}
B_endpoints = (B_0 + B_1) / 2
B_time      = (1 / D) * Integral(B(t) dt) from t_0 to t_1
```

* They coincide for a balance changing linearly over the whole interval.
* Intraperiod deposits, withdrawals and valuation jumps require the actual path for the time-weighted measure.
* Holder/PPS uses remaining principal `C(t)`; keep that denominator distinct from market value `B(t)`.
* Restored vault/PPS uses its captured-checkpoint trapezoid denominator. See source coverage below before selecting a scope.

### Vault/PPS capital

The compatible vault checkpoints use this trapezoid denominator:

```text theme={null}
V_bar = (1 / D) * Sum(((V_j + V_{j+1}) / 2) * (u_{j+1} - u_j))
```

| Symbol            | Definition                                                                                               |
| ----------------- | -------------------------------------------------------------------------------------------------------- |
| `u_0`, `u_n`, `D` | Period start, end and elapsed seconds                                                                    |
| `u_j`             | Start, in-period checkpoint times and end                                                                |
| `V_j`             | Last compatible supply \* PPS / 10^6 at or before `u_j`; final endpoint selects through `u_n - 1` second |
| `V_bar`           | Average raw capital; output truncates to integer units                                                   |

* Keep checkpoint products and weighted sums unrounded until final output/rate calculation.
* This compatibility denominator uses the retained checkpoint selection. V1 boundary valuation uses exact confirmed-block state.

## Legacy source coverage

| PPS scope                 | Supported inputs                                                                            |
| ------------------------- | ------------------------------------------------------------------------------------------- |
| Holder/depositor          | Named Kaia USDT vault; existing position journal and immutable QA-selected price batches    |
| Holder with omitted vault | Supported only when all indexed account history belongs to the verified USDT book           |
| Vault                     | Named Kaia USDT vault; compatible Data Pipeline valuation checkpoints and trapezoid capital |
| Protocol / other assets   | `503` until historical membership and asset mapping are proven                              |
| Other `accountedBy` modes | Existing calculation paths; require separate validation                                     |

**Cautions**

* Specify holder/PPS `endDate` explicitly. It is inclusive; `2026-09-07` requires evidence through `2026-09-08T00:00:00Z`.
* Today, uncaptured periods and incomplete price/history evidence return `503` until collection completes.
* Selected price batches retain source IDs and integer values. Later source revisions can select different inputs.
* Verified reconstruction establishes those inputs and periods. Identity with an issued original requires that original's evidence.

## Export evidence

| Header                               | Retain                                                          |
| ------------------------------------ | --------------------------------------------------------------- |
| `Superearn-Legacy-Capital-Policy`    | Holder principal or vault trapezoid policy                      |
| `Superearn-Legacy-Accounting-Policy` | Restored holder/PPS policy when applicable                      |
| `Superearn-Legacy-Result`            | `recalculated` classification                                   |
| `Superearn-Legacy-Earnings-Source`   | Selected QA prices or Pipeline PPS                              |
| `Superearn-Legacy-Evidence`          | Policy, price batches, journal, related-event proof and periods |

* Preserve the exact request, response and headers with each export.
* Missing prices, history, capital or QA evidence returns a specific `legacy_*_unavailable` error.