Data Conventions

APR format, snapshot intervals, reward types, and response envelope specification.

APR Format

APR is stored as a decimal: 0.05 = 5%. Display by multiplying by 100.

Field	Description
`apr_net`	Total APR including base yield + incentive rewards. Point-in-time from last sync.
`base_apr`	Native protocol yield only (lending rate, share price accrual), before rewards.
`apr_forward`	Forward-looking estimate (when available).

Invariant: apr_net = base_apr + SUM(vault_rewards.apr)

Protocols without identifiable rewards set base_apr = apr_net and rewards = [].

Type	Description	Examples
`token_incentive`	Protocol token emissions	MORPHO, ARB, SPK
`points`	Non-transferable point programs	Various
`trading_fee`	LP trading fees	Curve, Uniswap
`strategy`	Sub-strategy yields	Yearn strategies

Data	Interval	Storage
Vault snapshots (raw)	30 minutes	`vault_snapshots` table
Hourly aggregates	1 hour	TimescaleDB continuous aggregate
Daily aggregates	1 day	TimescaleDB continuous aggregate
Risk scores	30 minutes	Recomputed by risk calculator
Oracle freshness	15 seconds	Redis (real-time)

All API responses follow a standard envelope format.

{
  "success": true,
  "data": { ... }
}

{
  "success": true,
  "data": [ ... ],
  "pagination": {
    "page": 1,
    "limit": 10,
    "total": 247,
    "totalPages": 25
  }
}

{
  "success": false,
  "error": {
    "message": "Vault not found",
    "code": "NOT_FOUND"
  }
}

Code	Meaning
200	Success
400	Bad request (invalid parameters)
404	Resource not found
429	Rate limited
500	Internal server error

All timestamps are in ISO 8601 format with UTC timezone: 2026-02-25T12:00:00Z.

Large numbers (TVL, APR) are returned as strings to preserve precision: "125000000" not 125000000.