Skip to main content
The SuperEarn Data API is a public, read-only REST service that provides verified on-chain state, historical balances, returns, allocations, and withdrawal tracking. The developer documentation is organized into two primary tracks:
  • 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.
All monetary amounts in the Data API are denominated in raw integer atoms or standard decimal units. When performing calculations or displaying values to users, maintain exact decimal handling: 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)). For EarnUSDT, shares convert first to seCDV and then to USDT (6 decimals). Always retain integer floors at each contract step before dividing by 10decimals10^{\text{decimals}}.
  • Fixed-rate (BoringVault, e.g. EarnJPYC) valuation: Fixed-rate vault shares always have 18 decimals, while Accountant.getRate() is denominated in the base asset’s decimals (10^18 for JPYC, 10^6 for USDT). Convert shares to base-asset units using floor(shares * rate / 10^18) (valuationMethod: "accountant-rate"). Inspect GET /v1/vault-read-plans to read each vault’s machine-readable architecture ("yearn" vs "boring-vault"), valuationMethod ("yearn-free-funds" vs "accountant-rate"), and withdrawal.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 (minAmountOut or minimumShares).

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 in quality.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 these null values rather than converting them to zero.

Scope selection

Endpoints such as /v1/balances and /v1/earnings support filtering by scope:
  • Protocol scope (omit account and vault): 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 account and vault): Tracks a specific wallet’s holdings within a single vault.

Next steps