> ## 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 nine 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 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 V3 vault risk surface covers nine chains: `eth`, `arb`, `base`, `opt`, `pol`, `bsc`, `avax`, `gnosis`, `sol`.

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>

***

## What V3 returns

The V3 vault surface (`/v3/vaults/{address}`) returns a composite letter grade, per-category contributors, the full `pass` / `warn` / `fail` criteria taxonomy, and coverage disclosure. The framework is versioned and pinnable via `framework_version` and `grading_scheme`.

The underlying `risk` envelope is preserved verbatim on every V3 response, so if you already consume the standard Webacy `risk` format you can adopt V3 incrementally — read the new fields when you're ready, ignore them until then.

<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 `risk.score` envelope. 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&framework_version=v1&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&framework_version=v1&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", "framework_version": "v1", "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 when a new framework or scheme version ships — see [Pinning the framework](/api-reference/vault-risk-v3/framework-methodology#pinning-the-framework).
</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="Screen and Monitor Vault Risk" icon="shield-halved" href="/digital-assets/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>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.