> ## 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 Integration Guide

> Integrate Webacy vault risk ratings for ERC-4626 vaults with composite letter grades, per-category contributors, and continuous monitoring on six chains.

Webacy rates the risk of ERC-4626 vaults so you can screen, list, and monitor DeFi vaults with confidence. Every vault is scored against a versioned risk framework that spans seven categories — from smart-contract quality to counterparty and hack/exploit history — and rolls up into a single composite grade you can act on.

This page is the starting point. It orients you to what the vault risk surface gives you, how the new **V3** API differs from **V2**, and where to go to integrate.

## What you get

<CardGroup cols={2}>
  <Card title="Composite letter grade" icon="award">
    A single `A+`–`F` grade (plus a 0–100 score and star rating) summarizing overall vault risk.
  </Card>

  <Card title="Per-category contributors" icon="layer-group">
    See exactly which of the seven risk categories drove the grade, each with its own score and weight.
  </Card>

  <Card title="Criteria taxonomy" icon="list-check">
    A dense `pass` / `warn` / `fail` breakdown across the framework's individual criteria.
  </Card>

  <Card title="Coverage disclosure" icon="gauge">
    Every response tells you how many criteria are live versus planned — no hidden gaps.
  </Card>
</CardGroup>

The seven categories are `smart_contract`, `operational_governance`, `asset_collateral`, `market_liquidity`, `counterparty`, `hack_exploit_history`, and `chain_infrastructure`. The vault risk surface covers six EVM chains: `eth`, `arb`, `base`, `opt`, `pol`, `bsc`.

The composite grade uses the [standard 11-band letter scale](/api-reference/vault-risk-v3/framework-methodology#letter-grade-mapping): `A+` (lowest risk) through `F` (highest), with no `E` grade.

<Note>
  Want vault risk coverage on a chain that's not listed? [Contact the team](mailto:info@webacy.com) — we're actively expanding chain coverage.
</Note>

***

## V3 vs V2

You have two API surfaces. **V3 is the newest** and the recommended target for new integrations; **V2 is frozen but fully supported** for existing ones.

|                 | V3 (recommended)                                                               | V2 (stable)                                         |
| --------------- | ------------------------------------------------------------------------------ | --------------------------------------------------- |
| Path            | `/v3/vaults/{address}`                                                         | `/vaults/{address}`                                 |
| Output          | Composite letter grade, per-category contributors, criteria taxonomy, coverage | 0–100 risk rating, tier, listing verdict, risk tags |
| Framework       | Versioned, pinnable (`framework_version`, `grading_scheme`)                    | Single fixed model                                  |
| `risk` envelope | Verbatim pass-through of V2                                                    | Native                                              |

The V2 `risk` envelope is preserved verbatim on every V3 response, so you can adopt V3 incrementally — read the new fields when you're ready, ignore them until then. See the [V2 → V3 migration guide](/api-reference/migrations/v2-to-v3) for the full contract.

<Warning>
  **Score polarity: higher means worse.** V3 numeric scores (`composite.score`, category scores, contributor scores) run 0–100 where **0 is the lowest risk and 100 is the highest** — the same direction as the V2 `risk.score`. The letter grade keeps the conventional mapping (`A+` is best, `F` is worst), so a low numeric score earns a high letter grade. If you build dashboards, make sure higher numbers sort and color as *worse*. See the [polarity warning](/api-reference/vault-risk-v3/v3-overview#score-polarity) for the worked example.
</Warning>

***

## Quickstart

Fetch the full V3 risk decomposition for a single vault. You need a Webacy API key ([sign up here](https://developers.webacy.co/billing)) and the vault's contract address and chain.

<CodeGroup>
  ```bash cURL theme={null}
  curl -X GET "https://api.webacy.com/v3/vaults/0x0deFfd509197aAD5207d2A55862835b467E8128F?chain=eth&grading_scheme=v2" \
    -H "x-api-key: YOUR_API_KEY"
  ```

  ```typescript TypeScript theme={null}
  const res = await fetch(
    'https://api.webacy.com/v3/vaults/0x0deFfd509197aAD5207d2A55862835b467E8128F?chain=eth&grading_scheme=v2',
    { headers: { 'x-api-key': process.env.WEBACY_API_KEY } }
  );
  const vault = await res.json();

  console.log(`Grade: ${vault.composite.grade}`);        // e.g. "C-"
  console.log(`Score: ${vault.composite.score}`);        // 0–100, higher = worse
  console.log(`Clamped by upstream: ${vault.composite.clamped_by_upstream}`);
  ```

  ```python Python theme={null}
  import requests

  res = requests.get(
      "https://api.webacy.com/v3/vaults/0x0deFfd509197aAD5207d2A55862835b467E8128F",
      params={"chain": "eth", "grading_scheme": "v2"},
      headers={"x-api-key": "YOUR_API_KEY"},
  )
  vault = res.json()
  print(vault["composite"]["grade"], vault["composite"]["score"])
  ```
</CodeGroup>

<Tip>
  Pin `framework_version` and `grading_scheme` from your very first call. Both default, but pinning guarantees reproducible scoring across the deprecation window — see [Pin from day one](/api-reference/migrations/v2-to-v3#pin-from-day-one).
</Tip>

The framework taxonomy itself is available from a **public** endpoint (no API key required): `GET /v3/framework` returns the full category and criteria list, so your client never drifts from the live framework.

***

## Where to go next

<CardGroup cols={2}>
  <Card title="Vault Risk V3 Overview" icon="circle-info" href="/api-reference/vault-risk-v3/v3-overview">
    The V3 contract: versioning, polarity, upstream floor, and categories.
  </Card>

  <Card title="Vault Detail (V3)" icon="vault" href="/api-reference/vault-risk-v3/get-vault-risk-detail-v3">
    Full request/response reference for `GET /v3/vaults/{address}`.
  </Card>

  <Card title="Framework Methodology" icon="calculator" href="/api-reference/vault-risk-v3/framework-methodology">
    How composite scores are derived and why the framework is API-driven.
  </Card>

  <Card title="Framework Taxonomy" icon="sitemap" href="/api-reference/vault-risk-v3/get-framework">
    The public endpoint returning the canonical category and criteria list.
  </Card>

  <Card title="V2 → V3 Migration" icon="arrow-right" href="/api-reference/migrations/v2-to-v3">
    Endpoint mapping, deprecation contract, and pinning guidance.
  </Card>

  <Card title="Screen and Monitor Vault Risk" icon="shield-halved" href="/guides/vault-risk-screening">
    Step-by-step integration guide for screening and continuous monitoring.
  </Card>

  <Card title="Vault Risk Intelligence" icon="chart-line" href="/vault-risk-intelligence">
    The data and signals available — verdicts, withdrawal risk, history, depeg.
  </Card>

  <Card title="Vault Incidents" icon="triangle-exclamation" href="/vault-incidents">
    A curated timeline of vault exploits, depegs, and governance failures.
  </Card>
</CardGroup>