Skip to main content
Scalar API reference · Reporting TL;DR: holdings, cost, PnL and returns · Data API overview 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.

Choose a workflow

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

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): On CooldownVault (EarnUSDT), capital that has undergone a redemption request and is in cooldown or awaiting claim ([Unit: asset]), preserving 100% principal as a fixed non-earning claim. On fixed-rate BoringVault (EarnJPYC), pending AtomicQueue shares remain in your wallet accruing yield until redeemSolve, so redemptionReceivable = "0" and the holding stays inside positionValue.
    • Total balance identity:
  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.

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

EarnUSDT withdrawals follow the CooldownVault request-and-claim flow, while production EarnJPYC fixed-rate withdrawals use AtomicQueue requests and atomic settlement (redeemSolve). Both models are indexed by GET /v1/accounts/{account}/redemptions; inspect withdrawal.kind in GET /v1/vault-read-plans to distinguish their semantics (on AtomicQueue, cooldownEndsAt is the request settlement deadline, and once settled as status: "claimed" the cleared on-chain slot reports assets: "0" while the settled payout is recorded in claim.assets):
Variable-Rate (CooldownVault) vs Fixed-Rate (BoringVault + AtomicQueue) Comparison & Cautions (EarnUSDT · EarnJPYC)

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.

Pattern 6: Billing & financial reporting queries (EarnUSDT and EarnJPYC)

EarnJPYC production uses the 18-decimal fixed-rate share token 0x794B606e216c24b6675804fFa081CdDa8586FA59 (eip155:8217:0x794b606e216c24b6675804ffa081cdda8586fa59, deployed at block 230960963) on Kaia (8217) and is listed in the production Data API catalog (GET /v1/vaults, GET /v1/vault-read-plans). The endpoint mappings below apply to both EarnUSDT and EarnJPYC (GET /v1/harvests remains variable-rate SuperVault-only and returns 503 accountant_history_unavailable for fixed-rate BoringVaults). Always verify meta.quality before using responses in financial reports, and never treat an unavailable (503) or incomplete (null) field as a zero balance. For direct contract calls, see the EarnJPYC on-chain integration.

7-Item Share-Valuation Settlement & Variable vs Fixed-Rate Vault Comparison (EarnUSDT · EarnJPYC)

For partners settling EarnJPYC and EarnUSDT using share-valuation accounting (“equity/share” model) rather than interest-payout accounting, the following 7 data points map to the same endpoints and fields across variable-rate (EarnUSDT, CooldownVault) and fixed-rate (EarnJPYC, BoringVault + AtomicQueue) vaults:
Accounting Caution (Preventing Double-Counting): On variable-rate CooldownVault, shares burn on request and move from positionValue into redemptionReceivable (totalValue = positionValue + redemptionReceivable). On fixed-rate BoringVault (AtomicQueue), shares stay in wallet shares (positionValue) and continue accruing yield until redeemSolve, so redemptionReceivable = "0". Never add /redemptions?status=pending data[].assets on top of positionValue on fixed-rate vaults.

EarnUSDT and EarnJPYC request and response examples

1. Point-in-time balances for a supported vault

EarnJPYC response example (GET /v1/balances, valuation=pps):
In the default valuation=pps mode, EarnJPYC returns quality.status: "complete" as shown above. Fixed-rate vaults currently return 503 accounting_rpc_unavailable when valuation=estimated_nav is requested, and reconciliation.quality.status: "unavailable" ("accounting_rpc_unavailable") when include=reconciliation is passed.

2. Daily opening & closing valuation, share/asset amounts, and TWR (GET /v1/earnings)

3. Supported-vault activity and withdrawal requests

Follow page.nextCursor for complete history and inspect quality.status (or meta.quality when present) before using results in a report.
For fixed-rate EarnJPYC (AtomicQueue), shares represents the offered vault shares, assets represents the open request slot value, and cooldownEndsAt is the settlement deadline rather than a cooldown maturity. Once the solver settles the request via redeemSolve, status becomes "claimed" and the cleared on-chain slot reports assets.value: "0", while the actual settled payout (receivedAssets) is recorded in claim.assets.value (for example, "480000"). Refer to the withdrawal comparison above and verify the vault’s read plan.

4. EarnJPYC daily open & close valuation (GET /v1/earnings, 2026-11-16 KST)

EarnJPYC reports values at 18-decimal precision (JPYC). On days without external flows (inflows: "0", outflows: "0"), opening.totalValue + pnl = closing.totalValue (1571386.344881141536243 + 83.067262772204247 = 1571469.41214391374049) holds exactly.

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 (10610^6 for USDT/EarnUSDT, 101810^{18} for JPYC/EarnJPYC and fixed-rate BoringVault shares) 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 the appropriate router (SuperEarnRouter for variable-yield vaults; Router and AtomicQueue for fixed-rate vaults).