> ## 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.

# Data API integration patterns

> Implement vault discovery, portfolio screens, activity feeds, and withdrawal lifecycle tracking.

[Scalar API reference](https://api.superearn.io/v1/docs) · [Reporting TL;DR: holdings, cost, PnL and returns](/en/developers/financial-data#tldr) · [Data API overview](/en/developers/data-access)

This guide walks through standard integration patterns for applications, client dashboards, and wallet interfaces using the SuperEarn Data API.

For institutional partner accounting, IFRS-grade financial reporting, and audit invariants, see [Balances, cost and returns](/en/developers/financial-data).

## Choose a workflow

| Use case                  | Read sequence                                                                                                                                                                                                                                                 | Result                                                                                   |
| ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------- |
| **Product list & yields** | [vaults](https://api.superearn.io/v1/docs#tag/vaults/GET/vaults) → [vault](https://api.superearn.io/v1/docs#tag/vaults/GET/vaults/\{vault}) → [apy](https://api.superearn.io/v1/docs#tag/apy/GET/apy)                                                         | Active products, asset metadata, and observed trailing yields                            |
| **Wallet portfolio**      | [vaults](https://api.superearn.io/v1/docs#tag/vaults/GET/vaults) → [balances](https://api.superearn.io/v1/docs#tag/balances/GET/balances)                                                                                                                     | Active position values, remaining cost basis, unrealized PnL, and redemption receivables |
| **Activity stream**       | [activity](https://api.superearn.io/v1/docs#tag/accounts/GET/accounts/\{account}/activity)                                                                                                                                                                    | Historical transaction log of deposits, withdrawals, share transfers, and claims         |
| **Withdrawal tracker**    | [redemptions](https://api.superearn.io/v1/docs#tag/accounts/GET/accounts/\{account}/redemptions) + [liquidity](https://api.superearn.io/v1/docs#tag/allocations/GET/vaults/\{vault}/liquidity)                                                                | Request lifecycle stages, cooldown timer, claimability, and vault liquidity reserves     |
| **Allocation breakdown**  | [manifest](https://api.superearn.io/v1/docs#tag/catalog/GET/manifest) → [graph](https://api.superearn.io/v1/docs#tag/allocations/GET/vaults/\{vault}/graph) + [allocations](https://api.superearn.io/v1/docs#tag/allocations/GET/vaults/\{vault}/allocations) | Underlying strategy exposures, protocol debt, and venue breakdown                        |
| **Institutional close**   | [earnings](https://api.superearn.io/v1/docs#tag/earnings/GET/earnings)                                                                                                                                                                                        | Periodic opening/closing balances, flows, realized/unrealized PnL, and TWR returns       |

## Pattern 1: Vault catalog and market discovery

To display available investment vaults and their current performance:

1. **List all vaults**: Call `GET /v1/vaults` to fetch the catalog of deployed SuperVaults. Filter by `status: "active"` for current deposit targets, but retain inactive vaults for historical portfolio views.
2. **Fetch vault metadata**: Call `GET /v1/vaults/{vault}` to retrieve contract addresses, underlying assets, decimals, and operational state.
3. **Fetch trailing yield**: Call `GET /v1/apy?vault={vault}` to obtain the official trailing 7-day share price APY (`pps_apy`).
4. **Fetch benchmark rates**: Call `GET /v1/market-rates` to compare vault yield against external reference benchmarks (such as Morpho, Aave, and Kaia ecosystem rates).

```bash theme={null}
# Example: Discover active vaults
curl -s "https://api.superearn.io/v1/vaults" | jq '.data[] | {id: .id, name: .name, status: .status}'
```

## Pattern 2: Wallet portfolio screen

To present a complete portfolio view for a connected user wallet:

1. **Query current balances**: Call `GET /v1/balances?account={walletAddress}&at={timestamp}`. `at` is required (e.g. `at=2026-09-01T00:00:00Z`); pass the current time or a specific historical boundary. A request without `at` returns `400`.
2. **Decompose the total balance and share holdings**:
   * **Total managed assets (`totalValue`)**: The combined sum of active positions and pending redemption claims (`positionValue + redemptionReceivable`, `[Unit: asset]`).
   * **Active share balance (`shares`)**: Raw vault LP token balance held by the user (`[Unit: shareToken]`, metadata defined in `shareToken`).
   * **Active position value (`positionValue`)**: Capital actively deployed in the vault earning daily yield (`shares * PPS`, `[Unit: asset]`).
   * **Redemption receivables (`redemptionReceivable`)**: Capital that has undergone a redemption request and is in cooldown or awaiting claim (`[Unit: asset]`). Preserves 100% principal as a fixed non-earning claim.
   * **Total balance identity**:
     ```text theme={null}
     Total Value = Active Position Value + Redemption Receivables
     ```
3. **Display cost and unrealized gain**:
   * Show `costBasis` as the net remaining invested capital (`[Unit: asset]`).
   * Show `unrealizedPnl = positionValue - costBasis` as the unrealized gain on active shares (`[Unit: asset]`).
4. **Preserve quality flags**: Inspect `quality.status`. If historical acquisition evidence is still indexing, `costBasis` and `unrealizedPnl` may be returned as `null` while verified balances remain available. Preserve the `null` status rather than displaying zero.

For exact derivation of share valuation and integer floors, see the [Boundary value equation](/en/developers/financial-data#boundary-value).

## Pattern 3: Transaction and activity stream

To render an account's transaction history:

1. **Call account activity**: Call `GET /v1/accounts/{account}/activity` with the optional filters `type` (`position`, `redemption` or `balance`) and `vault`, and paginate with `limit` (1\~100) and `cursor`. The endpoint has no `start` / `end` time filters; sending them returns `400`.
2. **Classify rows by `type`, then by `operation`**: Every row carries a `type` discriminator equal to the `type` filter value that selects it. `position` and `balance` rows carry an uppercase `operation` field; `redemption` rows have no `operation` and carry `status` instead. There are no `deposit`, `redemption_request`, `claim`, `transfer_in` or `transfer_out` values.

   | `type` (filter and row) | What the row describes                                                                          | Classifier field | Values                                               |
   | ----------------------- | ----------------------------------------------------------------------------------------------- | ---------------- | ---------------------------------------------------- |
   | `position`              | A change in the account's vault share position (`vault`, `shares`)                              | `operation`      | `MINT`, `BURN`, `SEND`, `RECEIVE`                    |
   | `redemption`            | A redemption request and its settlement (`redemptionId`, `assets`, `shares`)                    | `status`         | `pending`, `claimed`                                 |
   | `balance`               | A change in the account's balance of a tracked token (`assetId`, `amount`, `balance`, `locked`) | `operation`      | `MINT`, `BURN`, `SEND`, `RECEIVE`, `LOCKUP`, `FETCH` |

   `operation` values:

   * `MINT`: New units are minted to the account. On a `position` row this is a deposit that issues vault shares.
   * `BURN`: Units are burned from the account. On a `position` row this is a share burn made directly by the account.
   * `SEND`: Units leave the account in a transfer; `shares` is negative on a `position` row. A redemption submitted through the router appears as a `SEND` of shares to the router together with a `redemption` row.
   * `RECEIVE`: Units arrive in the account in a transfer, including an in-kind custody migration.
   * `LOCKUP` (`balance` only): The account's locked amount changes; `amount` is signed and `locked` shows the result.
   * `FETCH` (`balance` only): A balance snapshot read from the chain when the token is first tracked for the account. It is not a transfer: `amount` is 0 and `transactionHash` is `null`.

   `redemption` rows: `status` is `pending` until settlement and `claimed` afterwards. The claim does not produce a separate row; the same row gains `claimedAt`, `claimTransactionHash` and `receivedAssets`.

   `operation` is published as a nullable string, so handle an unrecognized or `null` value without failing.
3. **Netting rule**: The activity feed exposes transaction-level netting. If multiple operations occur in a single transaction, inspect the net flow to match the user's on-chain balance change.

## Pattern 4: Withdrawal lifecycle tracker

Redemptions in SuperEarn follow a two-step Request-and-Claim process via the CooldownVault to ensure orderly liquidity management:

```text theme={null}
[1. Request] ──► [2. Pending Cooldown] ──► [3. Claimable] ──► [4. Settled]
  Router           Waiting period             Vault has         Cash paid
  redemption       (100% principal,           sufficient        to user
  submitted        non-earning)               liquidity         wallet
```

| Stage            | Trigger / Condition                           | API Indicator                        | Consumer Action                                                               |
| ---------------- | --------------------------------------------- | ------------------------------------ | ----------------------------------------------------------------------------- |
| **1. Request**   | User calls `redeem` on `SuperEarnRouter`      | Transaction submitted                | Store the returned `requestId`                                                |
| **2. Pending**   | Request registered in CooldownVault           | `redemptions[].status = "pending"`   | Display remaining cooldown countdown timer                                    |
| **3. Claimable** | Cooldown timer elapsed (`cooldownEnd <= now`) | `redemptions[].status = "claimable"` | Verify vault liquidity (`/allocations/.../liquidity`) before initiating claim |
| **4. Settled**   | Keeper or user executes `claim`               | `redemptions[].status = "claimed"`   | Remove from `redemptionReceivable`; balance moves to wallet cash              |

**Key operational considerations**

* **Non-earning during cooldown**: Once a redemption request is confirmed on-chain, the burned shares no longer participate in vault share-price growth. The principal is 100% protected and locked as a nominal claim.
* **Liquidity buffer**: Before calling `claim` directly, check the vault's available cash reserves via `GET /v1/allocations/vaults/{vault}/liquidity`. In normal operations, protocol keepers automatically execute claims on behalf of users as liquidity allows.

## Pattern 5: Pagination, cursors, and query rules

When iterating through large historical datasets or account histories:

* **Cursor pagination**: All paginated list endpoints (e.g. `/v1/earnings`, `/v1/harvests`, `/v1/accounts/{account}/activity`) return a `page` object with `page.nextCursor` and `page.hasMore`. Pass `page.nextCursor` as the `cursor` query parameter in the subsequent request. `/v1/balances` returns a single snapshot and is not paginated.
* **Empty intermediate pages**: Continue fetching until `page.hasMore` is `false` (`page.nextCursor` is then `null`). Intermediate pages may occasionally contain zero items if non-matching records were filtered internally.
* **Short pages**: On `/v1/earnings` interval queries, a page may contain fewer rows than `limit` because of a server work budget, so always follow `page.nextCursor` until `page.hasMore` is `false` instead of stopping at a short page.
* **Timezones and cutoffs**:
  * Timestamps in query parameters support full ISO-8601 formatting (e.g. `start=2026-09-01T00:00:00+09:00`).
  * `GET /v1/harvests` requires both `start` and `end` as whole-second RFC 3339 timestamps with an explicit offset (e.g. `start=2026-09-01T00:00:00Z`); a date-only value such as `start=2026-09-01` returns `400`.
  * Use `timezone=Asia/Seoul` or specify an offset when requesting calendar intervals (`interval=day` or `interval=month`).
  * Use `cutoff=HH:mm:ss` to set custom local closing hours.

## Integration checklist

* [ ] Use `totalValue` (or `positionValue + redemptionReceivable`) to represent a user's complete managed balance.
* [ ] Retain raw integer precision in contract atoms and divide by token decimals (10^6) only for display.
* [ ] Inspect `quality.status` and `quality.reasons` on every response; preserve `null` values where evidence is pending.
* [ ] Handle cursor-based pagination completely: follow `page.nextCursor` until `page.hasMore` is `false`.
* [ ] Direct users through `SuperEarnRouter` for deposits and withdrawals; do not interact with `CooldownVault` directly.

## Related guides

| Guide                                                                | Description                                                                        |
| -------------------------------------------------------------------- | ---------------------------------------------------------------------------------- |
| [Data API overview](/en/developers/data-access)                      | Environments, base URLs, integration surfaces, and token decimals                  |
| [Balances, cost and returns](/en/developers/financial-data)          | 4 core audit invariants, pro-rata cost basis, PnL recognition, and return formulas |
| [Valuation and harvest reporting](/en/developers/accrual-accounting) | Vault lockedProfit buffer mechanics, strategy NAV, and harvest allocation          |
| [Scalar API reference](https://api.superearn.io/v1/docs)             | Interactive schema documentation for all endpoints                                 |