Balances, cost and returns

​

TL;DR

• Total Balance: totalValue = positionValue + redemptionReceivable
• Shares vs Value: shares represents the vault LP share token balance (shareToken unit), while positionValue represents those shares valued in underlying assets (shares × PPS, asset unit).
• Pending Redemption Units: redemptionReceivable is denominated in underlying asset units (asset), NOT share tokens. Upon redemption, shares are burned/locked and the exact asset claim is deposited into the CooldownVault, so it sums directly with positionValue.
• Cost Basis: Tracks historical acquisition cost of active shares using pro-rata moving average cost.
• Unrealized PnL Change: A period flow (closing - opening), whereas opening.unrealizedPnl and closing.unrealizedPnl are boundary balance sheet stocks.
• Rate conventions: Present return.periodRate and return.apr first. return.apy is computed for every period with a defined return; below 7 days it is a hypothetical annual extrapolation, so prefer return.apr and return.periodRate for short windows.
• Preserve nulls: Check quality.status and quality.reasons. Missing historical evidence leaves dependent fields as null. Preserve these nulls rather than converting them to zero.

​

API Request & Response Field Reference

​

Unit System

​

GET /v1/balances (Point-in-Time Balance Snapshot)

​

Request Parameters

​

Response Fields (data[].assets[])

​

GET /v1/earnings (Period PnL and Returns)

​

Request Parameters

​

Response Fields (data[].assets[])

​

The 4 core audit invariants

• Call GET /v1/earnings with interval=all and a start at or before the account’s first activity, so that opening.totalValue is 0. Take start from openedAt on GET /v1/accounts/{account}/positions (any earlier instant also works) and set end to the reporting boundary. The row’s inflows, outflows and pnl are then the lifetime totals.
• inflows and outflows are netted per transaction, recognize withdrawals when the redemption claim is paid, and in wallet scope include share transfers valued at the vault share value at the transfer operation. They are not total cash deposited or withdrawn. For a custody migration, the migrated shares enter the receiver’s inflows at value: e.g. an inflow of 21,509,075.692925 = carried cost 21,503,019.316660 + embedded gain 6,056.376265, where the gain is reported in netTransferredUnrealizedPnl.
• null inflows, outflows or pnl mean the check is not evaluable for that row (see quality.reasons), not that it failed.
• Do not mix these figures with totalEarnings from /v1/accounts/{account}/positions; the two figures are computed differently and do not reconcile.
• The lifetime read can take 10 seconds or more uncached; run it as its own request.

​

Scope

• Resolve the chain-qualified vault.id through /v1/vaults; retain inactive holdings.
• Each asset has its own {chainId, address, decimals}. Combine amounts only within that identity.
• A wallet scope follows its on-chain address. Beneficial-owner consolidation requires verified address ownership, effective dates and transfer links in a separate partner ledger. A transfer alone establishes no common-owner mapping.
• Omitting account aggregates holder investment performance. Operator revenue requires a separate accounting scope; strategy gain/loss comes from harvest reports.

​

One request: a KST daily report

• closing.totalValue = opening.totalValue + inflows - outflows + pnl
• With complete cost/PnL evidence: pnl = realizedPnl + unrealizedPnlChange - netTransferredUnrealizedPnl
• The example closes at September 9 00:00 KST; the next day opening uses the same boundary. opening.block / closing.block identify the confirmed states strictly before those times.

​

Change the reporting period

• KST daily/monthly reports follow the selected local calendar. IANA zones track DST; fixed offsets keep a constant clock rule.
• For daily/monthly holdings, read every row opening and closing; use interval=hour for hourly boundaries. A time-weighted average holding needs a separate calculation policy.
• Query any full period with interval omitted. Matching adjacent TWRs link geometrically: 1 + full-period rate = Product(1 + row rate). Require the same scope, valuation, policy and complete evidence; preserve precision and query the whole period for its annual equivalents.
• Read every page before closing a report. Preserve the query, response and evidence with the export.
• Exact input combinations, field definitions and error conditions: earnings · balances.

​

Valuation and return availability

​

Boundary value

Total Balance (totalValue) = Active Position Value (positionValue) + Redemption Receivables (redemptionReceivable)
Active Position Value (positionValue) = Held Shares (shares) × PPS

• Free funds: Free Funds = Reported Total Assets - Effective Locked Profit
• Underlying token allocation: Underlying Amount = floor(Held Shares * Free Funds / Total Supply)
• Asset conversion: For wrapper vaults (e.g. EarnUSDT converting through seCDV to USDT), the underlying amount is converted via the underlying vault exact convertToAssets at the same block, retaining integer floors before dividing by asset decimals (10^6).
• Redemption receivables: Nominal value of uncollected redemption claims.

• Multiply raw shares by free funds, divide by supply once, then convert the resulting underlying amount. The rounded pricePerShare quote is a diagnostic; multiplying a large holding by that quote loses precision.
• EarnUSDT converts through seCDV to USDT at the same block. Each contract conversion retains its integer floor.
• A valid empty vault has zero supply and zero held shares, yielding zero held value. Inconsistent share/supply state is unavailable.
• Free funds exclude effective locked profit; reported assets follow strategy reports. Estimated NAV can include supported strategy estimates before a report. Read the accrual coverage and adjustment rules before financial-statement use.
• Whole-vault valuation converts total supply once; per-wallet floors can produce a different sum.
• Periods are [t_0, t_1): an event at t_0 is included; an event at t_1 enters the next period.
• Adjacent periods share the same boundary snapshot. Hourly collection provides reusable boundaries; custom boundaries use verified archive reads.

• Unsupported conversion, unfinalized boundaries or missing evidence return an explicit error.
• Aggregate root assets once. Exclude nested claims already represented in the root valuation.
• Cooldown token conversion remains 1:1, and awaiting liquidity leaves unpaid claims at their nominal contract amounts. Strategy debt and shortfall are reconciled separately in the protocol book. Cooldown principal and settlement.

​

Cost and recognition

Unrealized PnL = Position Value - Cost Basis

• Position value (positionValue): Active shares under the selected valuation basis.
• Cost basis (costBasis): Verified remaining acquisition cost for active shares under the wallet convention (excludes nominal claims).
• Unrealized PnL (unrealizedPnl): Valuation gain or loss relative to cost basis at the boundary.

Allocated Cost = floor(Pre-movement Cost * Disposed Shares / Pre-movement Shares)
Remaining Cost = Pre-movement Cost - Allocated Cost
Realized PnL   = Disposal Consideration - Allocated Cost

• For a genuine share transfer, the allocated cost carries over to the receiving wallet.
• For a verified redemption or disposal, the difference between consideration received and allocated cost recognizes as realizedPnl.
• Custody migration (wallet-to-wallet transfer): Moving shares from an old custody wallet to a new custody wallet follows the same generic rule (wallet-transfer-pro-rata-v1) as any receipt-verified share transfer between any two wallets. SuperEarn keeps no address or entity registry and makes no beneficial-owner assertion. A full-balance transfer moves all remaining cost; a partial transfer moves floor(cost × shares sent / shares held) and the remainder stays with the sender. A pure transfer is not a disposal, so realized PnL is 0. See FAQ Q3.

​

PnL decomposition and reconciliation

Total PnL = Realized PnL + Unrealized PnL Change - Net Transferred Unrealized PnL

• Unrealized PnL Change (unrealizedPnlChange): Ending Unrealized PnL - Beginning Unrealized PnL
• Net Transferred Unrealized PnL (netTransferredUnrealizedPnl): Net embedded gain/loss entering the scope via share transfers:
  Net Transferred Unrealized PnL = Sum of Inbound(Market Value - Carried Cost) - Sum of Outbound(Market Value - Carried Cost)
  
• Reconciliation residual (residual): Verified books confirm that Total PnL - (Realized PnL + Unrealized PnL Change - Net Transferred Unrealized PnL) = 0. Nonzero residuals suppress return calculations.

​

Share transfer example

​

Example

​

Earnings

Ending Balance (closing.totalValue) = Beginning Balance (opening.totalValue) + Inflows - Outflows + PnL

PnL = Ending Balance (closing.totalValue) - Beginning Balance (opening.totalValue) - (Inflows - Outflows)

​

Period return

• Holding sub-periods: Across intervals without external flows, growth is:
  Sub-period Growth = Ending Balance / Beginning Balance
  
• Operation boundaries: At each external flow operation, portfolio values are measured immediately before and after the flow to isolate external capital additions and withdrawals from investment performance.
• Period TWR: All sub-period growth factors link geometrically:
  1 + Period TWR = Product(Sub-period Growth Factors)
  

​

Annualized rates

Linear APR   = Period TWR * (Year Seconds / Elapsed Seconds)
Compound APY = (1 + Period TWR) ^ (Year Seconds / Elapsed Seconds) - 1

• Linear APR (return.apr): Standard official annualized rate across all time horizons (1 hour, 1 day, 1 month).
• Compound APY (return.apy): Computed for every period with a defined return, including windows shorter than 7 days. It is null only when the period return is unavailable or the annualized result cannot be represented. Below 7 days it is a hypothetical annual equivalent that amplifies harvest and lock-release timing, so a non-null return.apy is not necessarily display-safe. Prefer return.apr and return.periodRate for short windows, and apply your own display threshold (e.g. hide apy when end - start < 7 days) if you need one.

​

PPS APY

PPS APY = (Closing PPS / Opening PPS) ^ (Year Seconds / Elapsed Seconds) - 1

• Opening PPS and Closing PPS are the observed share prices at the start and end of the trailing measurement window (start/end in the API response).
• Elapsed Seconds is the actual duration between observations, with Year Seconds = 31,536,000.

​

Contract interest

Period Interest = Credited Interest + Ending Accrued Interest - Beginning Accrued Interest

Accrued Interest = floor((Checkpoint Scaled Interest + Principal * Rate_bps * Active Accrual Seconds) / (10,000 * Year Seconds))

• Active Accrual Seconds: Elapsed seconds from max(last checkpoint, start time) to min(T, maturity). Maturity of 0 means uncapped.
• Credited Interest: Change in cumulative interest already credited to the claim ledger (credited).
• Principal & Rate: Checkpointed principal in raw token atoms and annual rate in basis points (100 bps = 1%).

​

Partner accounting FAQ

​

Report evidence

• Scalar defines balance fields, earnings fields and precision and APY fields.
• Apply separately supported impairment and reporting adjustments; see valuation and harvest reporting.
• Existing QA/legacy exports retain route-specific formulas and verified coverage; see legacy comparison.