Data Conventions

APR format, snapshot intervals, reward types, response envelope specification, timestamps, and numeric field formats.

APR Format

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

Field	Description
`apr_net`	Total APR including base yield plus incentive rewards. Point-in-time from last sync
`base_apr`	Native protocol yield only, before rewards
`apr_forward`	Forward-looking estimate when available

apr_net = base_apr + SUM(vault_rewards.apr)

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

Borrow-side rates use the opposite sign for incentives:

borrow_apr_net = borrow_apr - SUM(priced borrow reward APRs)

borrow_apr remains gross. borrow_reward_apr is the priced rebate total and borrow_apr_net may be negative. Unpriced points contribute zero. Consumers must read borrow_incentive_status: unavailable means the net rate is unknown, while none means an authoritative check found no active incentive.

Reward Types

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

Every reward row has a side of supply or borrow. Supply rewards add to depositor yield; borrow rewards subtract from borrower cost. Do not combine the two sides.

Risk Scores

Range 0-10 where higher means stronger modeled resilience
Tiers Prime at 8.0 or above, Core from 5.0 to 7.9, Edge below 5.0
Vectors Asset 30, Platform and Strategy 30, Control and Governance 20, History 20
Recomputation Hourly sync cycles plus incident-triggered rescoring within minutes

Snapshot Intervals

Data	Interval	Storage
Vault snapshots	1 hour	`vault_snapshots` table
Hourly aggregates	1 hour	TimescaleDB continuous aggregate
Daily aggregates	1 day	TimescaleDB continuous aggregate
Risk scores	1 hour plus incident-triggered recalc	Risk score runs
Oracle freshness	15 seconds	Redis

Response Envelope

Successful non-paginated responses use data.

{
  "data": { ... }
}

Offset-paginated responses use meta with totals.

{
  "data": [ ... ],
  "meta": {
    "page": 1,
    "limit": 20,
    "total": 247,
    "totalPages": 13
  }
}

Cursor-style pages use hasMore.

{
  "data": [ ... ],
  "meta": {
    "page": 1,
    "limit": 20,
    "hasMore": false
  }
}

Errors use error.code and error.message.

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

There is no success key in the runtime envelope.

HTTP Status Codes

Code	Meaning
200	Success
400	Bad request for invalid parameters
401	Authentication required
403	Not permitted for the supplied key
404	Resource not found
429	Rate limited
500	Internal server error
503	Fail-safe or upstream unavailable

Timestamps

All timestamps are ISO 8601 UTC strings such as 2026-02-25T12:00:00Z.

Numeric Fields

Most amounts are JSON numbers, including tvl_usd, apr_net, and base_apr on vault rows. Some high-precision or database numeric fields serialize as strings, including total_score in selected live payloads, balance_raw, version_id, and graph totals such as totalUsd.

Data Conventions

On this page