Data API integration patterns

​

Choose a workflow

​

Pattern 1: Vault catalog and market discovery

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

# 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

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

​

Pattern 3: Transaction and activity stream

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

[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

• 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

• 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