{ "openapi": "3.1.0", "info": { "title": "ClariQ Public Scoring API", "version": "1.0.0-beta", "description": "Deterministic DeFi vault risk scores with inspectable evidence trails. Scale: 1.0 = safest, 5.0 = highest risk (risk-native). Every response flags its score_source; deterministic responses carry an engine version and a facts snapshot hash for reproducibility. Private beta — keys by direct engagement (partners@clariq.fi). Versioning: URL-versioned (/v1); within v1 changes are additive (new fields, enum values, optional params) — clients must tolerate unknown fields; breaking changes ship as /v2 with at least six months of overlap.", "contact": { "email": "partners@clariq.fi" } }, "servers": [ { "url": "https://api.clariq.fi" } ], "security": [ { "bearerAuth": [] } ], "paths": { "/v1/vaults": { "get": { "summary": "List covered vaults (catalog with market data)", "parameters": [ { "name": "chain", "in": "query", "schema": { "type": "string" } }, { "name": "protocol", "in": "query", "schema": { "type": "string" } }, { "name": "asset", "in": "query", "schema": { "type": "string" } }, { "name": "band", "in": "query", "schema": { "type": "string", "enum": [ "low", "moderate", "elevated", "high" ] } }, { "name": "score_source", "in": "query", "schema": { "type": "string", "enum": [ "deterministic", "estimate", "protocol_fallback", "pending" ] } }, { "name": "min_tvl", "in": "query", "schema": { "type": "number" } }, { "name": "min_apy", "in": "query", "schema": { "type": "number" } }, { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 } }, { "name": "cursor", "in": "query", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Catalog page", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Catalog" }, "examples": { "catalog_page": { "summary": "Filtered catalog page with cursor pagination", "value": { "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 } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/v1/vaults/{id}": { "get": { "summary": "One catalog record", "parameters": [ { "$ref": "#/components/parameters/VaultId" } ], "responses": { "200": { "description": "Catalog record", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CatalogItem" }, "examples": { "catalog_record": { "summary": "One catalog record", "value": { "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" } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Ambiguous" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/v1/scores/{id}": { "get": { "summary": "Risk score with full factor breakdown and kill switches", "parameters": [ { "$ref": "#/components/parameters/VaultId" } ], "responses": { "200": { "description": "Score payload (score_source tells you which methodology produced it; pending vaults return score: null)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Score" }, "examples": { "deterministic": { "summary": "Deterministic score with full factor breakdown", "value": { "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 } }, "pending": { "summary": "Vault not yet scorable — honest null, queued for evaluation", "value": { "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 } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Ambiguous" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/v1/facts/{id}": { "get": { "summary": "Evidence trail behind a score (per-fact verified/pending status)", "parameters": [ { "$ref": "#/components/parameters/VaultId" } ], "responses": { "200": { "description": "Facts payload", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Facts" }, "examples": { "evidence_trail": { "summary": "Evidence trail behind a deterministic score", "value": { "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" } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Ambiguous" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/v1/allocations": { "post": { "summary": "Allocation engine (early access — contact partners@clariq.fi)", "responses": { "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" }, "501": { "$ref": "#/components/responses/EarlyAccess" } } } } }, "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "description": "API key: Authorization: Bearer clq_live_…" } }, "parameters": { "VaultId": { "name": "id", "in": "path", "required": true, "description": "Vault identifier: slug (steakhouse-usdc), canonical id, chain:0xaddress, bare 0xaddress (409 if it exists on multiple chains), or DefiLlama pool UUID.", "schema": { "type": "string" } } }, "responses": { "BadRequest": { "description": "Malformed request or query parameter", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "invalid_request", "message": "limit must be an integer between 1 and 200.", "status": 400 } } } } }, "Unauthorized": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "unauthorized", "message": "Missing or invalid API key.", "status": 401 } } } } }, "NotFound": { "description": "No vault matches the identifier", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "not_found", "message": "No vault matches 'x'.", "status": 404 } } } } }, "Ambiguous": { "description": "A bare 0xaddress exists on multiple chains — retry as chain:0xaddress using one of the candidates", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "ambiguous_identifier", "message": "Address exists on multiple chains.", "status": 409, "candidates": [ "ethereum:0xbeef047a543e45807105e51a8bbefcc5950fcfba", "base:0xbeef047a543e45807105e51a8bbefcc5950fcfba" ] } } } } }, "RateLimited": { "description": "Rate limit or monthly quota exceeded — honor Retry-After", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "rate_limited", "message": "Rate limit exceeded.", "status": 429 } } } } }, "EarlyAccess": { "description": "Endpoint not enabled for this key — contact partners@clariq.fi", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": { "code": "early_access", "message": "The allocation engine is in early access.", "status": 501 } } } } } }, "schemas": { "Factors": { "type": [ "object", "null" ], "description": "Per-factor risk scores, 1.0 (safest) to 5.0. Null factors were not assessable for this source.", "properties": { "technical": { "type": [ "number", "null" ] }, "financial": { "type": [ "number", "null" ] }, "operational": { "type": [ "number", "null" ] }, "systemic": { "type": [ "number", "null" ] }, "complexity": { "type": [ "number", "null" ] }, "frontend": { "type": [ "number", "null" ] }, "legal": { "type": [ "number", "null" ] }, "chain": { "type": [ "number", "null" ] } }, "required": [ "technical", "financial", "operational", "systemic", "complexity", "frontend", "legal", "chain" ], "additionalProperties": true }, "Score": { "type": "object", "properties": { "vault": { "type": [ "string", "null" ] }, "canonical_id": { "type": [ "string", "null" ] }, "chain": { "type": [ "string", "null" ] }, "protocol": { "type": [ "string", "null" ] }, "name": { "type": [ "string", "null" ] }, "score": { "type": [ "number", "null" ], "minimum": 1, "maximum": 5 }, "band": { "type": [ "string", "null" ], "enum": [ "low", "moderate", "elevated", "high", null ] }, "band_map": { "type": "string" }, "score_source": { "type": "string", "enum": [ "deterministic", "estimate", "protocol_fallback", "pending" ] }, "methodology": { "type": [ "string", "null" ], "enum": [ "deterministic_engine", "analyst_assessment", "protocol_default", null ] }, "score_scope": { "type": [ "string", "null" ], "enum": [ "vault", "protocol", null ] }, "score_status": { "type": [ "string", "null" ] }, "factors": { "$ref": "#/components/schemas/Factors" }, "kill_switches": { "type": [ "object", "null" ], "description": "Tri-state per named condition. NOT_APPLICABLE = the facts to evaluate this condition are not collected yet; the check honestly reports it did not run.", "additionalProperties": { "type": "string", "enum": [ "TRIGGERED", "CLEAR", "NOT_APPLICABLE" ] } }, "kill_switches_tripped": { "type": [ "integer", "null" ] }, "missing_fields": { "type": [ "array", "null" ], "items": { "type": "string" } }, "missing_vault_fields": { "type": [ "array", "null" ], "items": { "type": "string" } }, "evidence": { "type": [ "string", "null" ] }, "engine_version": { "type": [ "string", "null" ] }, "framework_version": { "type": [ "string", "null" ] }, "facts_snapshot": { "type": [ "string", "null" ], "pattern": "^0x[0-9a-f]{64}$" }, "facts_collected_at": { "type": [ "string", "null" ] }, "assessed_at": { "type": [ "string", "null" ] }, "scored_at": { "type": [ "string", "null" ] }, "stale": { "type": "boolean" }, "collection_queued": { "type": "boolean" } }, "required": [ "vault", "canonical_id", "score", "band", "score_source", "score_status", "stale" ], "additionalProperties": true }, "FactEntry": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "verified", "pending" ] }, "value": {}, "source": { "type": [ "string", "null" ] }, "hours": { "type": [ "number", "null" ] }, "tier1_count": { "type": [ "integer", "null" ] }, "tier2_count": { "type": [ "integer", "null" ] }, "latest_audit_date": { "type": [ "string", "null" ] }, "team_doxxed": { "type": [ "boolean", "null" ] }, "multisig": { "type": [ "string", "null" ] }, "known_exploit": { "type": [ "boolean", "null" ] }, "unreimbursed_exploit": { "type": [ "boolean", "null" ] }, "exploit_last_date": { "type": [ "string", "null" ] }, "real_pct": { "type": [ "number", "null" ] }, "emissions_pct": { "type": [ "number", "null" ] }, "speculative_pct": { "type": [ "number", "null" ] }, "is_mainnet": { "type": [ "boolean", "null" ] }, "l2beat_stage": { "type": [ "string", "null" ] }, "sequencer_model": { "type": [ "string", "null" ] }, "bridge_control": { "type": [ "string", "null" ] } }, "required": [ "status" ], "additionalProperties": true }, "Facts": { "type": "object", "properties": { "vault": { "type": [ "string", "null" ] }, "canonical_id": { "type": [ "string", "null" ] }, "facts_snapshot": { "type": [ "string", "null" ] }, "collected_at": { "type": [ "string", "null" ] }, "facts_completeness": { "type": "string", "enum": [ "complete", "partial" ] }, "facts": { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/FactEntry" } }, "pending_fields": { "type": "array", "items": { "type": "string" } }, "kill_switches_tripped": { "type": [ "integer", "null" ] }, "engine_version": { "type": [ "string", "null" ] }, "note": { "type": "string" } }, "required": [ "vault", "canonical_id", "facts_completeness", "facts", "pending_fields" ], "additionalProperties": true }, "CatalogItem": { "type": "object", "properties": { "vault": { "type": [ "string", "null" ] }, "canonical_id": { "type": "string" }, "name": { "type": [ "string", "null" ] }, "protocol": { "type": [ "string", "null" ] }, "chain": { "type": [ "string", "null" ] }, "asset": { "type": [ "string", "null" ] }, "vault_address": { "type": [ "string", "null" ] }, "defillama_pool_id": { "type": [ "string", "null" ] }, "tvl_usd": { "type": [ "number", "null" ] }, "apy": { "type": [ "number", "null" ] }, "apy_base": { "type": [ "number", "null" ] }, "apy_reward": { "type": [ "number", "null" ] }, "market_data_as_of": { "type": [ "string", "null" ] }, "score": { "type": [ "number", "null" ] }, "band": { "type": [ "string", "null" ] }, "score_source": { "type": "string" }, "score_status": { "type": [ "string", "null" ] }, "scored_at": { "type": [ "string", "null" ] }, "links": { "type": "object", "properties": { "score": { "type": [ "string", "null" ] }, "facts": { "type": [ "string", "null" ] } }, "additionalProperties": true } }, "required": [ "vault", "canonical_id", "score", "band", "score_source" ], "additionalProperties": true }, "Catalog": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/CatalogItem" } }, "pagination": { "type": "object", "properties": { "next_cursor": { "type": [ "string", "null" ] }, "limit": { "type": "integer" }, "total": { "type": "integer" } }, "required": [ "next_cursor", "limit", "total" ], "additionalProperties": true } }, "required": [ "data", "pagination" ], "additionalProperties": true }, "Error": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string" }, "message": { "type": "string" }, "status": { "type": "integer" }, "candidates": { "type": "array", "items": { "type": "string" } } }, "required": [ "code", "message", "status" ], "additionalProperties": true } }, "required": [ "error" ], "additionalProperties": true } } } }