# Credora by RedStone — Full Documentation for LLMs

> Credora provides transparent, unified risk ratings for decentralized finance (DeFi) protocols. Powered by RedStone, Credora runs 100,000+ Monte Carlo market simulations to assess risk across vaults, lending pools, and stablecoins.

---

## Table of Contents

1. [Overview](#overview)
2. [DeFi Rating Scale](#defi-rating-scale)
3. [GraphQL API Reference](#graphql-api-reference)
4. [Authentication](#authentication)
5. [Ratings Query](#ratings-query)
6. [Filtering & Pagination](#filtering--pagination)
7. [Example Queries & Responses](#example-queries--responses)
8. [Agent Integration (MCP & A2A)](#agent-integration-mcp--a2a)
9. [Methodology](#methodology)
10. [Protocol Implementations](#protocol-implementations)
11. [FAQ](#faq)
12. [Links & Resources](#links--resources)

---

## Overview

Credora is the new standard in DeFi risk assessment. We produce credit-style ratings for DeFi products — including Morpho vaults, Spark savings pools, and isolated lending markets — based on quantitative risk analysis.

**Key Metrics:**
- **PSL (Probability of Significant Loss)**: The annualized probability of a ≥1% loss on deposited capital
- **Rating**: A letter grade from AAA (safest) to D (default/loss) derived from PSL
- **Publish Date**: When the rating was last updated (YYYY-MM-DD format)

**Core Capabilities:**
- Unified DeFi credit ratings across protocols
- 100,000+ Monte Carlo market simulations per assessment
- Real-time data integration via RedStone oracle infrastructure
- Programmatic API access via GraphQL
- AI agent integration via MCP (Model Context Protocol) and A2A (Agent-to-Agent)

---

## DeFi Rating Scale

Credora uses a credit-rating-inspired scale designed specifically for DeFi risk:

| Rating | Risk Level | Description |
|--------|-----------|-------------|
| AAA | Lowest risk | Extremely low probability of significant loss. Reserved for the safest DeFi products. |
| AA | Very low risk | Very low probability of loss. High-quality protocols with strong risk management. |
| A | Low risk | Low probability of loss. Well-managed products with minor risk factors. |
| BBB | Moderate risk | Moderate probability of loss. Adequate risk management but some exposure. |
| BB | Elevated risk | Elevated probability of loss. Notable risk factors present. |
| B | High risk | High probability of loss. Significant risk factors that require careful consideration. |
| CCC | Very high risk | Very high probability of loss. Multiple serious risk factors. |
| CC | Extremely high risk | Extremely high probability of loss. Severe risk concerns. |
| C | Near-certain loss | Near-certain significant loss. Critical risk factors. |
| D | Default/Loss | Active default or loss event has occurred. |

---

## GraphQL API Reference

### Endpoint

```
POST https://api.credora.io/graphql
Content-Type: application/json
ClientSecret: <your-api-key>
```

### Authentication

All API requests require a valid API key passed in the `ClientSecret` HTTP header.

**Requesting Access:**
1. Visit https://credora.network/request-api/
2. Fill in your details (name, email, project, use case)
3. Receive your `ClientSecret` API key upon approval

**Authentication Header:**
```
ClientSecret: your-api-key-here
```

**Authentication Error Response:**
```json
{
  "errors": [
    {
      "message": "Unauthorized: Invalid or missing API key",
      "extensions": {
        "code": "UNAUTHENTICATED",
        "hint": "Provide a valid API key in the 'ClientSecret' header"
      }
    }
  ]
}
```

---

## Ratings Query

### GraphQL Schema

```graphql
type Query {
  ratings(
    filter: RatingsFilter
    page: Int = 0
    limit: Int = 10
  ): RatingsResult!
}

type RatingsResult {
  totalCount: Int!
  items: [Rating!]!
}

type Rating {
  id: String!
  address: String!
  name: String!
  chainId: Int!
  protocol: String!
  ratingType: String!
  product: String!
  curator: Curator
  Metrics: Metrics!
}

type Curator {
  name: String!
}

type Metrics {
  rating: String!
  psl: Float!
  publishDate: String!
}

input RatingsFilter {
  protocol: [String]
  product: [String]
  ratingType: [String]
  chainId: [Int]
  curator: [String]
  address: [String]
}
```

### Field Definitions

| Field | Type | Description |
|-------|------|-------------|
| `id` | String | Unique identifier for the rated product |
| `address` | String | On-chain contract address of the rated product |
| `name` | String | Human-readable name of the rated product |
| `chainId` | Int | Standard EVM chain identifier (1 = Ethereum, 8453 = Base) |
| `protocol` | String | Protocol name (e.g., "morpho", "spark") |
| `ratingType` | String | "indicative" or "commissioned" |
| `product` | String | Product category (e.g., "vaults", "markets") |
| `curator.name` | String | Name of the vault curator (if applicable) |
| `Metrics.rating` | String | Letter rating on the DeFi scale (AAA–D) |
| `Metrics.psl` | Float | Probability of Significant Loss (annualized) |
| `Metrics.publishDate` | String | Date of last rating update (YYYY-MM-DD) |

---

## Filtering & Pagination

### Pagination

| Parameter | Type | Default | Range | Description |
|-----------|------|---------|-------|-------------|
| `page` | Int | 0 | 0+ | Zero-indexed page number |
| `limit` | Int | 10 | 1–1000 | Number of results per page |

### Available Filters

All filters accept arrays. Multiple values within a filter use **OR** logic; multiple filters use **AND** logic.

| Filter | Type | Example Values |
|--------|------|---------------|
| `protocol` | [String] | "spark", "morpho" |
| `product` | [String] | "vaults", "markets" |
| `ratingType` | [String] | "indicative", "commissioned" |
| `chainId` | [Int] | 1, 8453 |
| `curator` | [String] | "Gauntlet", "Steakhouse" |
| `address` | [String] | "0x0D05e6ec0A10f9fFE9229EAA785c11606a1d13Fb" |

**Filter Logic Example:**
```graphql
# This returns ratings where:
# (protocol = "Morpho" OR protocol = "Spark") AND (product = "vaults")
filter: { protocol: ["Morpho", "Spark"], product: ["vaults"] }
```

---

## Example Queries & Responses

### Get All Ratings (No Filter)

```graphql
query GetAllRatings {
  ratings(page: 0, limit: 10) {
    totalCount
    items {
      id
      address
      name
      chainId
      protocol
      ratingType
      product
      curator {
        name
      }
      Metrics {
        rating
        psl
        publishDate
      }
    }
  }
}
```

**Example Response:**
```json
{
  "data": {
    "ratings": {
      "totalCount": 16,
      "items": [
        {
          "id": "12377",
          "address": "0x1234...abcd",
          "name": "Morpho Blue USDC Vault",
          "chainId": 1,
          "protocol": "morpho",
          "ratingType": "indicative",
          "product": "vaults",
          "curator": {
            "name": "Gauntlet"
          },
          "Metrics": {
            "rating": "BBB",
            "psl": 0.002,
            "publishDate": "2025-11-30"
          }
        }
      ]
    }
  }
}
```

### Get Ratings by Protocol

```graphql
query GetSparkRatings {
  ratings(filter: { protocol: ["spark"] }, page: 0, limit: 10) {
    totalCount
    items {
      id
      name
      protocol
      Metrics {
        rating
        psl
        publishDate
      }
    }
  }
}
```

### Get Ratings by Chain

```graphql
query GetBaseRatings {
  ratings(filter: { chainId: [8453] }, page: 0, limit: 10) {
    totalCount
    items {
      id
      name
      chainId
      protocol
      Metrics {
        rating
        psl
      }
    }
  }
}
```

### Get Ratings by Curator

```graphql
query GetGauntletRatings {
  ratings(filter: { curator: ["Gauntlet"] }, page: 0, limit: 20) {
    totalCount
    items {
      id
      name
      curator {
        name
      }
      Metrics {
        rating
        psl
        publishDate
      }
    }
  }
}
```

### Get Rating by Address

```graphql
query GetRatingByAddress {
  ratings(filter: { address: ["0x0D05e6ec0A10f9fFE9229EAA785c11606a1d13Fb"] }) {
    items {
      id
      name
      address
      protocol
      Metrics {
        rating
        psl
        publishDate
      }
    }
  }
}
```

### Combined Filters

```graphql
query GetMorphoVaultsOnEthereum {
  ratings(
    filter: {
      protocol: ["morpho"]
      product: ["vaults"]
      chainId: [1]
    }
    page: 0
    limit: 50
  ) {
    totalCount
    items {
      id
      name
      address
      curator {
        name
      }
      Metrics {
        rating
        psl
        publishDate
      }
    }
  }
}
```

---

## Agent Integration (MCP & A2A)

Credora supports two standard AI agent protocols for direct machine-to-machine integration, enabling LLMs and autonomous agents to access DeFi risk ratings programmatically.

### MCP (Model Context Protocol)

The MCP endpoint allows any MCP-compatible AI agent or LLM application to use Credora as a tool.

- **Endpoint**: `https://mcp.credora.network/mcp`
- **Protocol**: MCP (streamable HTTP)
- **No authentication required** for MCP access
- **Use Case**: Add Credora ratings as a tool in Claude, GPT, or any MCP-compatible agent

**Integration Example (MCP Config):**
```json
{
  "mcpServers": {
    "credora": {
      "url": "https://mcp.credora.network/mcp"
    }
  }
}
```

### A2A (Agent-to-Agent Protocol)

The A2A endpoint provides standardized agent-to-agent communication following the EIP-8004 specification.

- **Agent Card**: `https://a2a.credora.network/.well-known/agent.json`
- **Protocol**: A2A v0.3.0
- **Agent Name**: Credora Ratings Oracle
- **Description**: A risk intelligence agent providing real-time credit ratings for DeFi vaults via A2A protocol

**Available A2A Tools:**

| Tool | Description | Parameters |
|------|-------------|------------|
| `get_ratings` | Fetch all Credora risk ratings for DeFi vaults across all protocols | None |
| `get_ratings_by_protocol` | Fetch ratings filtered by protocol | `protocol` (string): e.g., "morpho" or "spark" |

---

## Methodology

### Vault & Pool Risk Assessment

Credora's methodology for rating DeFi vaults and pools involves:

1. **Monte Carlo Simulation**: 100,000+ market scenarios are simulated to model potential outcomes
2. **Asset Risk Analysis**: Each collateral asset is evaluated for price volatility, liquidity depth, and oracle reliability
3. **Protocol Risk**: Smart contract security, governance mechanisms, and operational risk factors
4. **Market Risk**: Liquidation efficiency, collateral factor sensitivity, and correlated asset exposure
5. **PSL Calculation**: The probability of a ≥1% loss event is computed across all simulation paths
6. **Rating Assignment**: PSL is mapped to the DeFi rating scale (AAA–D)

### Rating Types

- **Commissioned**: Ratings requested and funded by the protocol/curator. Subject to full due diligence.
- **Indicative**: Ratings produced by Credora proactively. Based on publicly available data.

### What PSL Measures

PSL (Probability of Significant Loss) represents the annualized probability that a depositor in a given vault or pool would experience a loss of 1% or more on their supplied capital. It accounts for:

- Collateral price movements and correlations
- Liquidation mechanism effectiveness
- Smart contract and operational risks
- Market liquidity conditions

---

## Protocol Implementations

### Morpho

Credora rates Morpho vaults and isolated lending markets:
- **Vaults**: Curated lending strategies managed by professional vault curators (e.g., Gauntlet, Steakhouse, RE7 Labs)
- **Markets**: Individual isolated lending pairs with specific collateral/loan asset combinations

Documentation: https://credora.network/docs/protocol-implementations/morpho/

### Spark

Credora rates Spark savings and lending products:
- **Savings**: DAI Savings Rate (DSR) and related yield products
- **Markets**: Spark lending markets

---

## FAQ

**Q: How do I get API access?**
A: Visit https://credora.network/request-api/ and submit the form. Access is granted after review.

**Q: What does the rating mean?**
A: Ratings range from AAA (safest) to D (default). They represent the probability of significant loss for depositors. See the Rating Scale section above.

**Q: How often are ratings updated?**
A: Ratings are updated regularly as market conditions change. The `publishDate` field in the API indicates the last update.

**Q: What is PSL?**
A: PSL (Probability of Significant Loss) is the annualized probability of a ≥1% loss on deposited capital, based on 100,000+ Monte Carlo market simulations.

**Q: Is the API free?**
A: API access requires approval. Pricing details are discussed during the onboarding process.

**Q: What chains are supported?**
A: Currently Ethereum (chainId: 1) and Base (chainId: 8453). Additional chains are being added.

---

## Links & Resources

| Resource | URL |
|----------|-----|
| Website | https://credora.network |
| Data App | https://app.credora.network |
| Documentation | https://credora.network/docs/ |
| API Documentation | https://credora.network/docs/api-documentation/ |
| Ratings API | https://credora.network/docs/api-documentation/ratings/ |
| Methodologies | https://credora.network/docs/methodologies/ |
| Rating Scale | https://credora.network/docs/methodologies/defi-rating-scale/ |
| MCP Server | https://mcp.credora.network/mcp |
| A2A Agent Card | https://a2a.credora.network/.well-known/agent.json |
| Blog | https://credora.network/blog/ |
| Reports | https://credora.network/reports/ |
| Request API Access | https://credora.network/request-api/ |
| Request Rating | https://credora.network/request-rating/ |
| X/Twitter | https://x.com/CredoraNetwork |
| LinkedIn | https://www.linkedin.com/company/credoranetwork/ |
| Privacy Policy | https://credora.network/privacy-policy/ |
| Terms of Service | https://credora.network/terms-of-service/ |
| Agent Discovery | https://credora.network/.well-known/agent.json |
| OpenAPI Spec | https://credora.network/openapi.json |
| Security Contact | https://credora.network/.well-known/security.txt |