Data & API

Versioned base URL #

Every endpoint is prefixed by the rubric version. Breaking changes increment the minor component (e.g. v1.5.0 → v1.6.0); additive changes do not. Major versions overlap for at least 12 months after a new minor is released.

https://defirisk.co/api/v1.7.0/

Endpoints #

All endpoints return JSON wrapped in the envelope contract. No pagination cursor at v1 — the dataset is small enough to ship in a single payload per list endpoint.

Envelope contract #

Every successful response is a JSON object stamped with rubric_version, data_as_of, and generated_at at the top level, followed by a data payload. The stamps make every response self-citing.

{
  "rubric_version": "v1.7.0",
  "data_as_of": "2026-05-17T15:29:57Z",
  "generated_at": "2026-05-18T11:38:41Z",
  "risk_score": 17.09,
  "category_severities": { "1": 5.80, "2": 13.04, "5": 44.44 },
  "cap_applied": "none",
  "cap_reason": null,
  "data": {
    "protocol_data": {
      "protocol": {
        "slug": "aave-v3",
        "display_name": "Aave v3",
        "headline_grade": "B",
        "total_value_secured_usd": 14063906193,
        "risk_score": 17.09,
        "category_severities": { "1": 5.80, "2": 13.04, "5": 44.44 },
        "cap_applied": "none",
        "cap_reason": null
      }
    }
  }
}

The index.json / list envelopes omit the four M1 v4 fields — they are protocol-specific and only appear on protocol-detail responses and at the envelope top level. List rows are lightweight on purpose:

{
  "rubric_version": "v1.7.0",
  "data_as_of": "2026-05-05T12:41:36Z",
  "generated_at": "2026-05-06T22:06:43Z",
  "data": {
    "protocols": [
      {
        "slug": "aave-v3",
        "display_name": "Aave v3",
        "headline_grade": "B",
        "total_value_secured_usd": 14063906193,
        "status": "live",
        "has_active_incident": true
      }
    ]
  }
}

• rubric_version — the rubric this response was computed against. Grades are only meaningful against a specific rubric version.
• data_as_of — the snapshot timestamp of the underlying data (when the upstream pipeline last refreshed).
• generated_at — when this particular file was produced.
• data — the requested resource. An object keyed by resource type (e.g. data.protocols, data.protocol_data); never null.

M1 rubric fields (v1.7.0+)

Protocol records include the following additional fields introduced with the M1 v4 rubric:

• risk_score — numeric 0–100 (2 decimal places, per dump.py round(_, 2)). A core-five-weighted average of per-category severity scores plus a critical-red penalty (5 pts per critical red, capped at 15). Lower is safer. This is the primary input to the letter-grade bands.
• category_severities — Record<string, number>. Maps each category id (as a string, e.g. "1") to its 0–100 severity score. Gray factors are excluded from the denominator; 0 means all green or no graded factors.
• cap_applied — "none" | "D" | "F". When a core-five category has severity ≥ 60, the grade is capped to D; ≥ 90 caps to F. This field records whether a cap was applied.
• cap_reason — human-readable explanation of the cap (e.g. "Cat 5 severity 67 ≥ 60 (core-five cap)"), or null when cap_applied is "none".

Schema #

JSON Schema definitions for every resource type are published alongside the API and versioned in lockstep with the rubric. The schema is open under CC-BY 4.0; reuse it freely.

https://defirisk.co/api/v1.7.0/schema/envelope.json

Caching #

All API responses are static JSON files emitted by the build pipeline and served by the CDN. They carry standard HTTP cache headers. New rubric versions live at new paths; old paths are immutable.

License #

Everything we publish is licensed for unrestricted reuse, subject to attribution. Data is CC BY 4.0; code is MIT. Attribution to "DeFi Risk, rubric v1.7.0" suffices for any data reuse.

https://defirisk.co/api/v1.7.0/protocols.csv
https://defirisk.co/api/v1.7.0/factors.csv