# Data Types & Enums

All response fields use **camelCase**. Numeric risk scores are on a `0–10` scale (lower = safer). Dates are ISO 8601 strings.

### 6.1 Protocol Interfaces

```typescript
// Protocol list item — GET /v1/protocols, GET /v1/screener
interface ProtocolSummary {
  id: string;                       // e.g. "aave-v3" (DeFiLlama slug)
  slug: string | null;
  name: string;
  category: string | null;          // "Lending", "Dex", "Liquid Staking", …
  chains: string[];                 // e.g. ["Ethereum", "Arbitrum"]
  logoUrl: string | null;
  url: string | null;               // Protocol website
  twitter: string | null;
  coverageScore: number | null;     // 0–6 (data completeness)
  compositeScore: number | null;    // 0–10 composite risk (lower = safer)
  riskLevel: RiskLevel | null;
  tvlUsd: number | null;
  scoreHistory: number[];           // Last 12 composite scores, oldest → newest
  scoredAt: string | null;          // ISO 8601
}

// /v1/screener adds the per-dimension breakdown on each row
interface ScreenerRow extends ProtocolSummary {
  creditRisk: number | null;
  counterpartyRisk: number | null;
  liquidityRisk: number | null;
  oracleRisk: number | null;
  smartContractRisk: number | null;
  liquidityTrapRisk: number | null;
}

// Full protocol detail — GET /v1/protocols/{id}
interface ProtocolDetail {
  id: string;
  slug: string | null;
  name: string;
  category: string | null;
  chains: string[];
  coverageScore: number | null;
  tokenSymbol: string | null;
  auditCount: number | null;
  oracleConfig: unknown;
  description: string | null;
  url: string | null;
  logoUrl: string | null;
  twitter: string | null;
  parentSlug: string | null;
  listedAt: string | null;          // ISO 8601
  tvlUsd: number | null;
  tvl30d: number | null;            // 30d change as fraction (0.05 = +5%)
  chainTvls: ChainBreakdown[];      // Per-chain TVL + borrowed
  composite: number | null;         // Composite risk (0–10, lower = safer)
  riskLevel: RiskLevel | null;
  scoredAt: string | null;
  dimensions: Dimensions | null;    // Six-dimension breakdown with 30d trend
  scoreMetadata: object | null;     // Factor inputs & methodology detail
  scoreHistory: number[];
  audits: AuditRecord[];
  incidents: Incident[];
  similar: SimilarProtocol[];
}

interface ChainBreakdown {
  chain: string;                    // e.g. "Ethereum", "Solana"
  tvlUsd: number;
  borrowedUsd: number;
}

interface Dimensions {
  credit:        Dimension;
  counterparty:  Dimension;
  liquidity:     Dimension;
  oracle:        Dimension;
  smartContract: Dimension;
  liquidityTrap: Dimension;
}

interface Dimension {
  score: number | null;             // 0–10
  trend: number;                    // 30d delta vs prior score
  label: string;                    // "Credit", "Oracle", …
  desc: string;                     // One-line description
}

interface Incident {
  id: string;
  exploitDate: string | null;
  lossUsd: number | null;
  chain: string | null;
  cause: string | null;             // "Oracle Manipulation", "Reentrancy", …
  pocUrl: string | null;
  source: string | null;            // "rekt", "defihacklabs", …
}

interface AuditRecord {
  auditor: string | null;
  auditDate: string | null;
  findingsSummary: unknown;
  reportUrl: string | null;
}

interface SimilarProtocol {
  id: string;
  slug: string | null;
  name: string;
  category: string | null;
  logoUrl: string | null;
  compositeScore: number | null;
  tvlUsd: number | null;
}

type RiskLevel = 'very-low' | 'low' | 'moderate' | 'elevated' | 'high';
```

### 6.2 Stats Response (`GET /v1/stats`)

```typescript
interface Stats {
  protocolCount: number;
  chainCount: number;
  globalRiskIndex: number | null;       // Mean composite across scored protocols
  globalRiskDelta7d: number | null;     // 7d change in global risk index
  totalTvlUsd: number | null;
  recentExploitsCount: number;           // Exploits in last 7 days
  updatedAt: string;                     // ISO 8601
}
```

### 6.3 Envelope & Pagination

All endpoints wrap their payload:

```typescript
interface SingleResponse<T>    { success: true;  data: T }
interface PaginatedResponse<T> { success: true;  data: T[]; meta: PaginationMeta }
interface ErrorResponse        { success: false; data: null; error: { code, message, status, details? } }

interface PaginationMeta {
  total: number;
  page: number;
  limit: number;
  pageCount: number;
}
```

### 6.4 Risk Dimensions

The composite score is a weighted aggregate of up to six dimensions. Each is on a 0–10 scale (lower = safer). Dimensions that are not applicable to a protocol are returned as `null` (not zero) and their weight is redistributed proportionally.

| **Dimension** | **Weight** | **What it measures**                               |
| ------------- | ---------- | -------------------------------------------------- |
| smartContract | 25%        | Audit coverage, code quality, incidents            |
| counterparty  | 20%        | Governance, multisigs, upgrade rights, guardians   |
| credit        | 15%        | Collateralization, liquidations, utilisation caps  |
| liquidity     | 15%        | Depth, slippage, withdrawal routes under stress    |
| oracle        | 15%        | Price feed robustness, TWAP, manipulation surface  |
| liquidityTrap | 10%        | Exit restrictions, admin freezes, unsellable tails |

### 6.5 Score Band Reference

Risk levels are derived from the composite score (safety = 10 − composite):

| **Composite Score** | **Safety Score** | **riskLevel** | **Display Label** |
| ------------------- | ---------------- | ------------- | ----------------- |
| 0.0 – 1.5           | 8.5 – 10.0       | `"very-low"`  | Very Low Risk     |
| 1.6 – 3.0           | 7.0 – 8.4        | `"low"`       | Low Risk          |
| 3.1 – 4.5           | 5.5 – 6.9        | `"moderate"`  | Moderate Risk     |
| 4.6 – 6.0           | 4.0 – 5.4        | `"elevated"`  | Elevated Risk     |
| 6.1 – 10.0          | 1.0 – 3.9        | `"high"`      | High Risk         |


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.diapleo.com/api-reference/overview/data-types-and-enums.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.