Choose a workflow
Pattern 1: Vault catalog and market discovery
To display available investment vaults and their current performance:- List all vaults: Call
GET /v1/vaultsto fetch the catalog of deployed SuperVaults. Filter bystatus: "active"for current deposit targets, but retain inactive vaults for historical portfolio views. - Fetch vault metadata: Call
GET /v1/vaults/{vault}to retrieve contract addresses, underlying assets, decimals, and operational state. - Fetch trailing yield: Call
GET /v1/apy?vault={vault}to obtain the official trailing 7-day share price APY (pps_apy). - Fetch benchmark rates: Call
GET /v1/market-ratesto 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:- Query current balances: Call
GET /v1/balances?account={walletAddress}&at={timestamp}.atis required (e.g.at=2026-09-01T00:00:00Z); pass the current time or a specific historical boundary. A request withoutatreturns400. - 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 inshareToken). - Active position value (
positionValue): Capital actively deployed in the vault earning daily yield (shares * PPS,[Unit: asset]). - Redemption receivables (
redemptionReceivable): OnCooldownVault(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-rateBoringVault(EarnJPYC), pendingAtomicQueueshares remain in your wallet accruing yield untilredeemSolve, soredemptionReceivable = "0"and the holding stays insidepositionValue. - Total balance identity:
- Total managed assets (
- Display cost and unrealized gain:
- Show
costBasisas the net remaining invested capital ([Unit: asset]). - Show
unrealizedPnl = positionValue - costBasisas the unrealized gain on active shares ([Unit: asset]).
- Show
- Preserve quality flags: Inspect
quality.status. If historical acquisition evidence is still indexing,costBasisandunrealizedPnlmay be returned asnullwhile verified balances remain available. Preserve thenullstatus rather than displaying zero.
Pattern 3: Transaction and activity stream
To render an account’s transaction history:-
Call account activity: Call
GET /v1/accounts/{account}/activitywith the optional filterstype(position,redemptionorbalance) andvault, and paginate withlimit(1~100) andcursor. The endpoint has nostart/endtime filters; sending them returns400. -
Classify rows by
type, then byoperation: Every row carries atypediscriminator equal to thetypefilter value that selects it.positionandbalancerows carry an uppercaseoperationfield;redemptionrows have nooperationand carrystatusinstead. There are nodeposit,redemption_request,claim,transfer_inortransfer_outvalues.operationvalues:MINT: New units are minted to the account. On apositionrow this is a deposit that issues vault shares.BURN: Units are burned from the account. On apositionrow this is a share burn made directly by the account.SEND: Units leave the account in a transfer;sharesis negative on apositionrow. A redemption submitted through the router appears as aSENDof shares to the router together with aredemptionrow.RECEIVE: Units arrive in the account in a transfer, including an in-kind custody migration.LOCKUP(balanceonly): The account’s locked amount changes;amountis signed andlockedshows the result.FETCH(balanceonly): A balance snapshot read from the chain when the token is first tracked for the account. It is not a transfer:amountis 0 andtransactionHashisnull.
redemptionrows:statusispendinguntil settlement andclaimedafterwards. The claim does not produce a separate row; the same row gainsclaimedAt,claimTransactionHashandreceivedAssets.operationis published as a nullable string, so handle an unrecognized ornullvalue without failing. - 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 apageobject withpage.nextCursorandpage.hasMore. Passpage.nextCursoras thecursorquery parameter in the subsequent request./v1/balancesreturns a single snapshot and is not paginated. - Empty intermediate pages: Continue fetching until
page.hasMoreisfalse(page.nextCursoris thennull). Intermediate pages may occasionally contain zero items if non-matching records were filtered internally. - Short pages: On
/v1/earningsinterval queries, a page may contain fewer rows thanlimitbecause of a server work budget, so always followpage.nextCursoruntilpage.hasMoreisfalseinstead 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/harvestsrequires bothstartandendas whole-second RFC 3339 timestamps with an explicit offset (e.g.start=2026-09-01T00:00:00Z); a date-only value such asstart=2026-09-01returns400.- Use
timezone=Asia/Seoulor specify an offset when requesting calendar intervals (interval=dayorinterval=month). - Use
cutoff=HH:mm:ssto set custom local closing hours.
- Timestamps in query parameters support full ISO-8601 formatting (e.g.
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-rateCooldownVault, shares burn on request and move frompositionValueintoredemptionReceivable(totalValue = positionValue + redemptionReceivable). On fixed-rateBoringVault(AtomicQueue), shares stay in walletshares(positionValue) and continue accruing yield untilredeemSolve, soredemptionReceivable = "0". Never add/redemptions?status=pendingdata[].assetson top ofpositionValueon fixed-rate vaults.
EarnUSDT and EarnJPYC request and response examples
1. Point-in-time balances for a supported vault
GET /v1/balances, valuation=pps):
In the defaultvaluation=ppsmode,EarnJPYCreturnsquality.status: "complete"as shown above. Fixed-rate vaults currently return503 accounting_rpc_unavailablewhenvaluation=estimated_navis requested, andreconciliation.quality.status: "unavailable"("accounting_rpc_unavailable") wheninclude=reconciliationis passed.
2. Daily opening & closing valuation, share/asset amounts, and TWR (GET /v1/earnings)
3. Supported-vault activity and withdrawal requests
Followpage.nextCursor for complete history and inspect quality.status (or meta.quality when present) before using results in a report.
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(orpositionValue + redemptionReceivable) to represent a user’s complete managed balance. - Retain raw integer precision in contract atoms and divide by token decimals ( for
USDT/EarnUSDT, forJPYC/EarnJPYCand fixed-rateBoringVaultshares) only for display. - Inspect
quality.statusandquality.reasonson every response; preservenullvalues where evidence is pending. - Handle cursor-based pagination completely: follow
page.nextCursoruntilpage.hasMoreisfalse. - Direct users through the appropriate router (
SuperEarnRouterfor variable-yield vaults;RouterandAtomicQueuefor fixed-rate vaults).