> ## Documentation Index
> Fetch the complete documentation index at: https://docs.webacy.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Vault Risk API for ERC-4626 DeFi Vaults

> Use the Webacy vault endpoints for ERC-4626 risk ratings, share-price and TVL history, and structured due-diligence signals across DeFi vault strategies.

## Overview

The Vault Risk endpoints give you risk ratings and due diligence data for ERC-4626 vaults across 6 EVM chains. Ratings are computed by a multi-factor pipeline that evaluates vault structure, governance, liquidity, code quality, asset risk, performance, and protocol risk — producing 7 risk categories with 41 possible risk tags.

Each response includes a standard `risk` field in the same format used by all other Webacy risk endpoints (Threat Risks, Token Analysis, Depeg Monitor), so you can consume vault risk data using the same schema.

## Endpoints

<CardGroup cols={2}>
  <Card title="List Vaults" icon="list" href="/api-reference/vault-risk/list-erc-4626-vaults-with-risk-scores#list-erc-4626-vaults-with-risk-score">
    `GET /vaults` — Paginated list of all rated ERC-4626 vaults with risk ratings, filtering, sorting, and ecosystem aggregates
  </Card>

  <Card title="Vault Detail" icon="vault" href="/api-reference/vault-risk/get-vault-risk-detail#get-vault-risk-detail">
    `GET /vaults/{address}?chain={chain}` — Full risk decomposition with lending market data, vault composition, and code analysis findings.
  </Card>
</CardGroup>

***

## Key Concepts

### Risk Rating (0-100)

You get a composite risk rating for each vault, based on weighted signals across 7 categories:

| Category                    | Description                                                  |
| --------------------------- | ------------------------------------------------------------ |
| Vault Structure             | Architecture, upgradeability, and strategy complexity        |
| Governance & Access Control | Ownership model, admin controls, timelock configuration      |
| Liquidity & Withdrawal      | Withdrawal capacity, lockups, utilization, and bad debt      |
| Code Quality                | Contract verification, audits, and exploit history           |
| Asset & Market              | Underlying asset quality, depeg risk, and oracle reliability |
| Performance                 | Returns, TVL trends, maturity, and operational activity      |
| Protocol Risk               | Underlying protocol framework and curation status            |

<Tip>
  For a detailed breakdown of how this rating is computed — including all sub-rating weights, additive penalties, hard floors, and risk flags — see the [Rating Methodology](/api-reference/vault-rating).
</Tip>

### Risk Tiers

| Tier       | Rating | Interpretation                            |
| ---------- | ------ | ----------------------------------------- |
| `critical` | 75-100 | Severe risk, immediate attention required |
| `high`     | 50-74  | Elevated risk, close monitoring needed    |
| `medium`   | 25-49  | Moderate risk, review recommended         |
| `low`      | 0-24   | Normal conditions, low risk               |
| `unknown`  | N/A    | Vault has not been rated                  |

### Listing Verdicts

You get a listing verdict for each vault to help decide whether to surface it to users:

| Verdict           | Condition                              |
| ----------------- | -------------------------------------- |
| `do_not_list`     | Has blocking risk tags or rating >= 75 |
| `review_required` | Rating >= 55                           |
| `caution`         | Rating >= 30 or unrated                |
| `safe_to_list`    | Rating \< 30                           |

### Standard Risk Response

The `risk` field on each vault follows the same structure used by all Webacy risk endpoints:

```json theme={null}
{
  "risk": {
    "score": 100,
    "count": 4,
    "medium": 2,
    "high": 2,
    "overallRisk": 100,
    "issues": [
      {
        "score": 100,
        "tags": [
          {
            "type": "vault_performance_risk",
            "key": "vault-dormant",
            "name": "Dormant Vault",
            "description": "Vault has fewer than 10 on-chain events, indicating negligible activity.",
            "severity": 10,
            "context": {
              "detected_at": "2026-03-31T16:43:01.093Z"
            }
          }
        ],
        "categories": {
          "vault_performance_risk": {
            "key": "vault_performance_risk",
            "name": "Performance",
            "description": "Risk factors related to vault returns, TVL trends, maturity, and operational activity.",
            "tags": {
              "vault-dormant": true
            }
          }
        }
      }
    ]
  }
}
```

### Supported Chains

`eth`, `arb`, `base`, `opt`, `pol`, `bsc`

***

## Query Parameters

### Pagination

The list endpoint supports both offset-based and cursor-based pagination:

| Mode   | Parameters                                              | Description                                     |
| ------ | ------------------------------------------------------- | ----------------------------------------------- |
| Offset | `page` (default: 1), `pageSize` (default: 50, max: 500) | Traditional page-based pagination               |
| Cursor | `cursor`, `limit` (default: 100, max: 500)              | Opaque cursor for efficient large-set traversal |

### Filters

| Parameter         | Type    | Description                                                                                    |
| ----------------- | ------- | ---------------------------------------------------------------------------------------------- |
| `chain`           | string  | Filter by chain (`eth`, `arb`, `base`, `opt`, `pol`, `bsc`)                                    |
| `tier`            | string  | Filter by risk tier (`low`, `medium`, `high`, `critical`, `unknown`)                           |
| `protocol`        | string  | Filter by protocol (`morpho`, `aave`, `compound`, `euler`, `spark`, `fluid`, `beefy`, `yearn`) |
| `contractType`    | string  | Filter by type (`erc4626_vault`, `strategy_vault`, `lending_wrapper`, `bridge_vault`)          |
| `underlying`      | string  | Filter by underlying asset symbol (e.g., `USDC`)                                               |
| `underlyingRisk`  | string  | Underlying risk tier (`battle_tested`, `medium_risk`, `high_risk`, `crypto`, `unknown`)        |
| `minTvl`          | number  | Minimum TVL in USD                                                                             |
| `minScore`        | number  | Minimum risk rating (0-100)                                                                    |
| `maxScore`        | number  | Maximum risk rating (0-100)                                                                    |
| `attentionNeeded` | boolean | Filter to vaults needing attention                                                             |
| `riskFlags`       | string  | Comma-separated risk tag keys to filter by                                                     |
| `riskFlagsMode`   | string  | How to combine risk flags: `any` (OR) or `all` (AND)                                           |
| `q`               | string  | Search by vault name, symbol, or address                                                       |

### Sorting

| Sort Key                   | Description                        |
| -------------------------- | ---------------------------------- |
| `score_desc` / `score_asc` | Risk rating (highest/lowest first) |
| `tvl_desc` / `tvl_asc`     | TVL (largest/smallest first)       |
| `apy_desc`                 | APY (highest first)                |
| `looping_desc`             | Looping rate (highest first)       |
| `name_asc`                 | Vault name (alphabetical)          |

***

## Vault Detail

The detail endpoint (`GET /vaults/{address}?chain={chain}`) returns everything from the list endpoint plus:

* **Looping markets** — Recursive lending positions with rates, collateral, and utilization
* **Vault composition** — Underlying asset allocation breakdown
* **Lending market data** — Protocol-specific metadata (curator, rewards, market allocations) with support for multiple lending markets
* **Webacy findings** — Smart contract code analysis results
* **LST collateral markets** — Liquid staking token redemption data

***

## Risk Tags Reference

### Vault Structure

| Tag                        | Name                 | Severity | Description                             |
| -------------------------- | -------------------- | -------- | --------------------------------------- |
| `vault-upgradeable`        | Upgradeable Contract | 6        | Proxy contract can be upgraded by admin |
| `vault-subvault`           | Subvault             | 3        | Vault-of-vault nested structure         |
| `vault-emergency-shutdown` | Emergency Shutdown   | 10       | Vault in emergency shutdown mode        |

### Governance & Access Control

| Tag                          | Name                 | Severity | Description                          |
| ---------------------------- | -------------------- | -------- | ------------------------------------ |
| `vault-eoa-owner`            | EOA Owner            | 6        | Owned by EOA (not multisig/timelock) |
| `vault-pause-capable`        | Pause Capable        | 4        | Has pause functionality              |
| `vault-pending-admin-change` | Pending Admin Change | 6        | Governance admin change pending      |
| `vault-no-timelock`          | No Timelock          | 6        | No timelock delay on admin actions   |
| `vault-low-timelock`         | Low Timelock         | 4        | Timelock shorter than recommended    |

### Liquidity & Withdrawal

| Tag                          | Name                  | Severity | Description                                  |
| ---------------------------- | --------------------- | -------- | -------------------------------------------- |
| `vault-redemption-closed`    | Redemption Closed     | 10       | Users cannot withdraw                        |
| `vault-high-looping`         | High Looping Exposure | 7        | Significant recursive lending exposure       |
| `vault-lockup-7d`            | 7-Day Lockup          | 5        | Lockup exceeding 7 days                      |
| `vault-deposit-closed`       | Deposit Closed        | 5        | No longer accepting deposits                 |
| `vault-withdrawal-delay`     | Withdrawal Delay      | 4        | Processing delay on withdrawals              |
| `vault-high-utilisation`     | Maxed Utilization     | 6        | Above 95% utilization                        |
| `vault-low-utilisation`      | Idle Utilization      | 3        | Below 10% utilization                        |
| `vault-bad-debt`             | Bad Debt              | 8        | Outstanding bad debt exceeding \$1,000       |
| `vault-morpho-low-liquidity` | Very Low Liquidity    | 7        | Underlying lending market liquidity very low |

### Code Quality

| Tag                         | Name                | Severity | Description                                |
| --------------------------- | ------------------- | -------- | ------------------------------------------ |
| `vault-unverified-contract` | Unverified Contract | 10       | Source code not verified on block explorer |
| `vault-no-audits`           | No Audits           | 6        | No known security audits                   |
| `vault-exploit-history`     | Exploit History     | 8        | Protocol has known exploit or hack         |
| `vault-not-battle-tested`   | Not Battle Tested   | 4        | Less than 6 months on mainnet              |

### Asset & Market

| Tag                               | Name                      | Severity | Description                               |
| --------------------------------- | ------------------------- | -------- | ----------------------------------------- |
| `vault-share-price-depeg`         | Share Price Depeg         | 8        | Share price deviated from expected peg    |
| `vault-oracle-warning`            | Oracle Warning            | 8        | Oracle reliability concerns               |
| `vault-lst-redemption-lag`        | LST Redemption Lag        | 5        | LST collateral with redemption delays     |
| `vault-synth-asset`               | Synthetic Asset           | 5        | Holds synthetic or wrapped assets         |
| `vault-supply-spike`              | Supply Spike              | 8        | Minted supply in 24h exceeds 40% of total |
| `vault-underlying-depegging`      | Underlying Depegging      | 7        | Underlying asset experiencing depeg       |
| `vault-underlying-depeg-critical` | Underlying Depeg Critical | 9        | Critical depeg severity on underlying     |

### Performance

| Tag                        | Name               | Severity | Description                             |
| -------------------------- | ------------------ | -------- | --------------------------------------- |
| `vault-dormant`            | Dormant Vault      | 10       | Fewer than 10 on-chain events           |
| `vault-negative-return`    | Negative Return    | 5        | Negative lifetime return                |
| `vault-low-tvl`            | Low TVL            | 4        | Below minimum TVL threshold             |
| `vault-inactive`           | Inactive Vault     | 4        | 10-50 on-chain events                   |
| `vault-new`                | New Vault          | 3        | Recently deployed, insufficient history |
| `vault-momentum-declining` | Momentum Declining | 4        | 1-month CAGR below 3-month CAGR         |
| `vault-capital-outflow`    | Capital Outflow    | 4        | Net capital outflow                     |
| `vault-high-fees`          | High Fees          | 4        | Above-average fees                      |
| `vault-beefy-eol`          | Beefy End of Life  | 8        | No longer actively maintained by Beefy  |
| `vault-strategy-loss`      | Strategy Loss      | 7        | Realized loss event                     |
| `vault-retired`            | Retired Vault      | 8        | No longer generating yield              |

### Protocol Risk

| Tag                            | Name            | Severity | Description                             |
| ------------------------------ | --------------- | -------- | --------------------------------------- |
| `vault-morpho-not-whitelisted` | Not Whitelisted | 5        | Not on the platform's curated whitelist |
| `vault-yearn-high-risk`        | Yearn High Risk | 7        | Elevated risk per Yearn framework       |

***

## Common Use Cases

| Use Case                    | Endpoint                              | Parameters                                     |
| --------------------------- | ------------------------------------- | ---------------------------------------------- |
| Dashboard overview          | `GET /vaults`                         | `sort=score_desc&pageSize=50`                  |
| Filter by chain             | `GET /vaults`                         | `chain=eth&tier=low&sort=tvl_desc`             |
| Find USDC vaults            | `GET /vaults`                         | `underlying=USDC&sort=apy_desc`                |
| High-TVL vaults only        | `GET /vaults`                         | `minTvl=1000000&sort=tvl_desc`                 |
| Vaults needing attention    | `GET /vaults`                         | `attentionNeeded=true&sort=score_desc`         |
| Search by name              | `GET /vaults`                         | `q=Morpho`                                     |
| Lending vaults with looping | `GET /vaults`                         | `protocol=morpho&riskFlags=vault-high-looping` |
| Single vault detail         | `GET /vaults/{address}?chain={chain}` | `address` = `0x1234...`, `chain` = `eth`       |

## Example Workflow

<Note>
  **Prerequisites:** You need an API key (passed via the `x-api-key` header), the base URL `https://api.webacy.com`, and for detail requests, the vault's contract address (`0x...`) and chain identifier (`eth`, `arb`, `base`, `opt`, `pol`, or `bsc`).
</Note>

### Screen a Vault Before Listing

```bash theme={null}
# 1. Search for the vault
curl -X GET "https://api.webacy.com/vaults?q=USDC-WLFI&chain=eth" \
  -H "x-api-key: YOUR_API_KEY"

# 2. Get full risk detail
curl -X GET "https://api.webacy.com/vaults/0x0deFfd509197aAD5207d2A55862835b467E8128F?chain=eth" \
  -H "x-api-key: YOUR_API_KEY"
```

### Monitor High-Risk Vaults

```bash theme={null}
# Get all critical-tier vaults needing attention
curl -X GET "https://api.webacy.com/vaults?tier=critical&attentionNeeded=true&sort=tvl_desc" \
  -H "x-api-key: YOUR_API_KEY"
```

## Related Resources

<CardGroup cols={2}>
  <Card title="Rating Methodology" icon="calculator" href="/api-reference/vault-rating">
    How vault risk ratings are computed: sub-ratings, weights, penalties, and floors
  </Card>

  <Card title="Depeg Monitor" icon="chart-line" href="/api-reference/depeg-monitor">
    Real-time depeg risk monitoring for stablecoins and pegged assets
  </Card>

  <Card title="Risk Tags Reference" icon="tags" href="/essentials/risk-tags">
    Complete list of all risk tags returned by Webacy risk endpoints
  </Card>
</CardGroup>