Data & API

Versioned base URL #

Every endpoint is prefixed by the rubric version. Breaking changes increment the minor component; additive changes do not. The current supported version is v1.7.0. A version may be retired with an explicit HTTP 410 response and migration notice.

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

Retired versions #

The selected local release candidate retires v1.5.0, v1.6.0. Its qualified local routing fixture returns 410 Gone with a JSON notice for each retired version root and every descendant. Clients must explicitly migrate to the current version and check its status and available data.

The local routing configuration is not installed in production. Deployment and production HTTP verification remain separate operations.

{
  "error": "api_version_retired",
  "api_version": "v1.5.0",
  "migration_url": "/data/"
}

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). One critical red blocks A; two or more force D or worse; three or more force F. Lower is safer. This is the primary input to the letter-grade bands, and core-five caps can lower the final grade further.
• 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. Successful responses carry standard HTTP cache headers. New rubric versions live at new paths. Versioned paths do not promise indefinite availability; an explicit retirement is recorded in the selected API lifecycle metadata and requires separately qualified HTTP routing.

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.

Nightly CSV: Planned; no CSV files are published yet.