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

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
  • EarnUSDT valuation: EarnUSDT shares represent ownership of the root vault. They convert first to seCDV via the root vault share value formula, and then seCDV converts to USDT. Always retain integer floors at each contract step before dividing by 1,000,000 (10^6).
  • 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).

​
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