- Data API: Operational patterns for discovering vaults, displaying user portfolios, tracking activities, and managing the withdrawal lifecycle.
- Partner Accounting: Accounting models, the 4 core audit invariants, pro-rata moving average cost basis, PnL recognition, and period-close reconciliation for institutional partners and auditors.
Environments and base URLs
All Data API endpoints use standard HTTP GET methods and return JSON payloads with ISO-8601 timestamps.
Integration surfaces
Depending on whether your application requires public reads, interactive quotes, user transactions, or automated settlement, choose the appropriate integration surface:Token units and decimals
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). Always check meta.quality before using responses in financial reports, and never treat an unavailable (503) or incomplete (null) response as a zero balance. For direct contract calls, see the EarnJPYC on-chain integration.
Critical calculation rules
- Variable-yield (
EarnUSDT) valuation: Variable-yield shares represent ownership of the root vault (valuationMethod: "yearn-free-funds",floor(shares * (totalAssets - effectiveLockedProfit) / totalSupply)). ForEarnUSDT, shares convert first toseCDVand then toUSDT(6 decimals). Always retain integer floors at each contract step before dividing by . - Fixed-rate (
BoringVault, e.g.EarnJPYC) valuation: Fixed-rate vault shares always have 18 decimals, whileAccountant.getRate()is denominated in the base asset’s decimals (10^18forJPYC,10^6forUSDT). Convert shares to base-asset units usingfloor(shares * rate / 10^18)(valuationMethod: "accountant-rate"). InspectGET /v1/vault-read-plansto read each vault’s machine-readablearchitecture("yearn"vs"boring-vault"),valuationMethod("yearn-free-funds"vs"accountant-rate"), andwithdrawal.kind("cooldown"vs"atomic-queue") fields. - Decimal arithmetic: Never use floating-point numbers for financial accounting. Always use arbitrary-precision decimal libraries or native integer math to prevent rounding drift.
- Slippage protection: When submitting router transactions, always specify explicit nonzero minimum output amounts (
minAmountOutorminimumShares).
Operational conventions and quality semantics
Caching and collection status
The Data API continuously precollects and indexes verified on-chain evidence for registered vaults and accounts. When querying historical ranges:quality.status = complete: All underlying on-chain blocks, transactions, and state proofs have been collected and verified.quality.status = partial: Some historical evidence is currently being indexed. The response contains specific error codes inquality.reasons(such as*_collection_pending).- Preserving nulls: Fields that depend on uncollected or unavailable evidence (e.g. missing historical acquisition marks) are returned as
null. Applications and reporting pipelines must preserve thesenullvalues rather than converting them to zero.
Scope selection
Endpoints such as/v1/balances and /v1/earnings support filtering by scope:
- Protocol scope (omit
accountandvault): Aggregates all managed assets across all published vaults. - Vault scope (specify
vault): Aggregates all share holders within that specific vault. - Wallet scope (specify
account): Tracks all holdings across all vaults for a specific wallet address. - Wallet–Vault scope (specify both
accountandvault): Tracks a specific wallet’s holdings within a single vault.