Deterministic DeFi vault risk scores with inspectable evidence trails. Base URL: https://api.clariq.fi
curl -H "Authorization: Bearer clq_live_…" \
https://api.clariq.fi/v1/scores/steakhouse-usdcconst res = await fetch('https://api.clariq.fi/v1/scores/steakhouse-usdc', {
headers: { Authorization: `Bearer ${process.env.CLARIQ_API_KEY}` },
});
if (!res.ok) {
const { error } = await res.json();
throw new Error(`${error.code}: ${error.message}`);
}
const score = await res.json();
console.log(score.score, score.band, score.score_source);import os, requests
res = requests.get(
"https://api.clariq.fi/v1/scores/steakhouse-usdc",
headers={"Authorization": f"Bearer {os.environ['CLARIQ_API_KEY']}"},
)
if not res.ok:
err = res.json()["error"]
raise RuntimeError(f"{err['code']}: {err['message']}")
score = res.json()
print(score["score"], score["band"], score["score_source"])Machine-readable spec: /v1/openapi.json (OpenAPI 3.1), with worked response examples on every endpoint.
Scores are risk-native: 1.0 = safest, 5.0 = highest risk. The band field bins the score (mapping version band_map.v1, reported on every response):
| Band | Score range |
|---|---|
| low | 1.0 – 2.0 |
| moderate | >2.0 – 3.0 |
| elevated | >3.0 – 4.0 |
| high | >4.0 – 5.0 |
| Endpoint | Description |
|---|---|
GET /v1/vaults | Catalog of covered vaults with market data (TVL, APY with base/reward split where sourced). Filters: chain, protocol, asset, band, score_source, min_tvl, min_apy; cursor pagination via limit + cursor. |
GET /v1/vaults/:id | One catalog record. |
GET /v1/scores/:id | Risk score: eight factors, 14 named kill-switch checks (tri-state), engine version, facts snapshot hash. |
GET /v1/facts/:id | The evidence trail: audits, contract verification, upgradeability, timelock, admin control, governance, incidents — each verified or pending, with its source. Never fabricated. |
POST /v1/allocations | Allocation engine — early access for institutional partners (501 until enabled for your key). |
:id accepts a slug (steakhouse-usdc), a canonical id, chain:0xaddress, a bare 0xaddress (409 with candidates if it exists on multiple chains), or a DefiLlama pool UUID.
Every score response says exactly where its number came from:
| score_source | Meaning |
|---|---|
deterministic | Computed by the versioned rules engine from verified facts. Carries engine_version and facts_snapshot — same facts in, same answer out; the score can be reproduced exactly. |
estimate | Analyst assessment (AI-assisted, human-reviewed) used as backfill while deterministic fact collection for this vault completes. No kill-switch map or facts snapshot. |
protocol_fallback | Vault-level facts incomplete; scored at protocol scope. Explicitly labeled, with missing_vault_fields enumerated — never presented as vault-specific. |
pending | Not enough verified evidence to score. score is null — we don't fabricate numbers. Requesting an unknown real vault queues it for evaluation. |
Kill-switch checks report TRIGGERED, CLEAR, or NOT_APPLICABLE. NOT_APPLICABLE means the facts to evaluate that condition aren't collected yet — the check honestly reports it did not run, rather than falsely passing.
These are real serializer outputs, regenerated from fixtures by generate-doc-samples.js — the shapes cannot drift from what the API actually returns.
{
"vault": "steakhouse-usdc",
"canonical_id": "morpho:ethereum:0xbeef047a543e45807105e51a8bbefcc5950fcfba",
"chain": "ethereum",
"protocol": "morpho",
"name": "Steakhouse USDC",
"score": 1.8,
"band": "low",
"band_map": "band_map.v1",
"score_source": "deterministic",
"methodology": "deterministic_engine",
"score_scope": "vault",
"score_status": "scored_vault",
"factors": {
"technical": 1.5,
"financial": 1.7,
"operational": 1.8,
"systemic": 2.4,
"complexity": 2,
"frontend": 1.6,
"legal": 2.1,
"chain": 1
},
"kill_switches": {
"K1": "CLEAR",
"K2": "CLEAR",
"K3": "CLEAR",
"K4": "NOT_APPLICABLE",
"K5": "CLEAR",
"K6": "CLEAR",
"K7": "CLEAR",
"K8": "CLEAR",
"K9": "CLEAR",
"LK1": "NOT_APPLICABLE",
"LK2": "NOT_APPLICABLE",
"LK3": "NOT_APPLICABLE",
"LK4": "NOT_APPLICABLE",
"LK5": "NOT_APPLICABLE"
},
"kill_switches_tripped": 0,
"missing_fields": [],
"missing_vault_fields": null,
"evidence": "/v1/facts/steakhouse-usdc",
"engine_version": "risk-engine.v2",
"framework_version": "1.0.0",
"facts_snapshot": "0x7394f12aa6bcadae84275a8a55d0ceeb306250fee439b32f51d738657f8b49ac",
"facts_collected_at": "2026-07-15T05:02:11Z",
"assessed_at": null,
"scored_at": "2026-07-15T06:15:00Z",
"stale": false
}{
"vault": "steakhouse-usdc",
"canonical_id": "morpho:ethereum:0xbeef047a543e45807105e51a8bbefcc5950fcfba",
"facts_snapshot": "0x7394f12aa6bcadae84275a8a55d0ceeb306250fee439b32f51d738657f8b49ac",
"collected_at": "2026-07-15T05:02:11Z",
"facts_completeness": "complete",
"facts": {
"audits": {
"status": "verified",
"tier1_count": 4,
"tier2_count": 0,
"latest_audit_date": "2026-03-01",
"source": "curated"
},
"contract_verified": {
"status": "verified",
"value": true,
"source": "onchain_probe"
},
"upgradeability": {
"status": "verified",
"value": "immutable",
"source": "onchain_probe"
},
"timelock": {
"status": "verified",
"hours": 48,
"source": "onchain_probe"
},
"admin_control": {
"status": "verified",
"value": "dao",
"source": "onchain_probe"
},
"governance": {
"status": "verified",
"team_doxxed": true,
"multisig": "5/9",
"source": "curated"
},
"incidents": {
"status": "verified",
"known_exploit": false,
"unreimbursed_exploit": false,
"exploit_last_date": null,
"source": "defillama_hacks"
},
"tvl_usd": {
"status": "verified",
"value": 312450000,
"source": "defillama"
},
"yield_composition": {
"status": "verified",
"real_pct": 5.4,
"emissions_pct": 0.8,
"speculative_pct": 0,
"source": "defillama"
},
"chain": {
"status": "verified",
"is_mainnet": true,
"l2beat_stage": null,
"sequencer_model": null,
"bridge_control": null,
"source": "l2beat"
}
},
"pending_fields": [],
"kill_switches_tripped": 0,
"engine_version": "risk-engine.v2"
}{
"vault": "newprotocol-usdc",
"canonical_id": "newprotocol:base:0x1234abcd1234abcd1234abcd1234abcd1234abcd",
"chain": "base",
"protocol": "newprotocol",
"name": "NewProtocol USDC",
"score": null,
"band": null,
"band_map": "band_map.v1",
"score_source": "pending",
"methodology": null,
"score_scope": null,
"score_status": "pending",
"factors": null,
"kill_switches": null,
"kill_switches_tripped": null,
"missing_fields": null,
"missing_vault_fields": null,
"evidence": "/v1/facts/newprotocol-usdc",
"engine_version": null,
"framework_version": null,
"facts_snapshot": null,
"facts_collected_at": null,
"assessed_at": null,
"scored_at": null,
"stale": false,
"collection_queued": true
}{
"data": [
{
"vault": "steakhouse-usdc",
"canonical_id": "morpho:ethereum:0xbeef047a543e45807105e51a8bbefcc5950fcfba",
"name": "Steakhouse USDC",
"protocol": "morpho",
"chain": "ethereum",
"asset": "USDC",
"vault_address": "0xbeef047a543e45807105e51a8bbefcc5950fcfba",
"defillama_pool_id": "1c1a3d5c-0000-4000-8000-demo00000000",
"tvl_usd": 312450000,
"apy": 6.2,
"apy_base": 5.4,
"apy_reward": 0.8,
"market_data_as_of": "2026-07-15T06:25:00Z",
"score": 1.8,
"band": "low",
"score_source": "deterministic",
"score_status": "scored_vault",
"scored_at": "2026-07-15T06:15:00Z",
"links": {
"score": "/v1/scores/steakhouse-usdc",
"facts": "/v1/facts/steakhouse-usdc"
}
}
],
"pagination": {
"next_cursor": "bW9ycGhvOmV0aGVyZXVtOjB4YmVlZg",
"limit": 50,
"total": 191
}
}Cursors are opaque — always take next_cursor from the response, never construct or modify one. limit caps at 200. A null next_cursor means you have the last page.
let cursor = null;
const vaults = [];
do {
const url = new URL('https://api.clariq.fi/v1/vaults');
url.searchParams.set('chain', 'ethereum');
url.searchParams.set('limit', '200');
if (cursor) url.searchParams.set('cursor', cursor);
const res = await fetch(url, {
headers: { Authorization: `Bearer ${process.env.CLARIQ_API_KEY}` },
});
const page = await res.json();
vaults.push(...page.data);
cursor = page.pagination.next_cursor;
} while (cursor);Send Authorization: Bearer clq_live_… on every /v1 request. Keys are issued to integration partners by direct engagement — partners@clariq.fi.
Treat keys as secrets: use them server-side only, never in URLs or query strings, and never in client bundles or repositories. To rotate, request a replacement key, run both during your cutover, then ask us to revoke the old one. If a key leaks, report it immediately and we will revoke it.
Every response carries rate-limit headers (X-RateLimit-Limit / -Remaining / -Reset); 429s include Retry-After — honor it and back off. Tiers differ by rate and monthly quota, not by data shape; your tier's numbers are stated in your partner agreement and readable live from the headers.
Responses carry an ETag. Send it back as If-None-Match to get a free 304 Not Modified when nothing changed:
$ curl -i -H "Authorization: Bearer clq_live_…" \
https://api.clariq.fi/v1/scores/steakhouse-usdc
HTTP/1.1 200 OK
ETag: "9f2b1c8e40aa317d5c6e2b91"
…
$ curl -i -H "Authorization: Bearer clq_live_…" \
-H 'If-None-Match: "9f2b1c8e40aa317d5c6e2b91"' \
https://api.clariq.fi/v1/scores/steakhouse-usdc
HTTP/1.1 304 Not ModifiedETags are opaque and per-representation — don't parse them or reuse them across endpoints.
{ "error": { "code": "not_found", "message": "No vault matches 'x'.", "status": 404 } }Codes: invalid_request 400 · unauthorized 401 · not_found 404 · ambiguous_identifier 409 · rate_limited / quota_exceeded 429 · internal 500 · early_access 501.
The API is URL-versioned; the current version is /v1. Within v1, changes are additive: new response fields, new enum values, and new optional query parameters may appear — write clients that tolerate unknown fields. Breaking changes ship as a new URL version (/v2) with at least six months of overlap and advance notice to every key holder.
The scoring methodology is versioned independently of the API surface — engine_version, framework_version, and band_map are reported on every response. A methodology revision is not an API version bump; record those fields alongside any score you store.
GET /livez and GET /readyz are unauthenticated and suitable for uptime monitors. livez reports process liveness; readyz returns 200 only when scored data is present and fresh (refreshed within 24h), 503 otherwise.
The qualitative framework — eight factors, kill switches, honesty guarantees, the facts pipeline — is public: methodology whitepaper. The quantitative specification (numeric factor weights, per-factor scoring bands, and kill-switch trigger thresholds) is proprietary and available to enterprise partners under NDA. The output band mapping (band_map.v1, table above) is public and versioned.
© 2026 clariq.fi — risk intelligence infrastructure. ClariQ provides informational risk analytics to businesses — not investment, financial, or legal advice. ClariQ is never compensated by the protocols it scores.