> ## 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.

# Screen and Monitor Vault Risk

> Screen ERC-4626 vaults before listing and monitor governance, liquidity, and code risk continuously across six EVM chains with sub-500ms verdicts.

In October 2023, a Yearn vault suffered a \$11.6M exploit due to a misconfigured withdrawal mechanism that went undetected for days. The vault's code was upgradeable, the admin key was an EOA, and there was no timelock. All of these were detectable signals. This guide shows you how to screen vaults before listing and monitor them continuously across 6 EVM chains.

## Why Vault Risk Screening Matters

<CardGroup cols={3}>
  <Card title="Compliance" icon="gavel">
    Automated listing verdicts help you meet due diligence requirements for DeFi integrations
  </Card>

  <Card title="Risk Management" icon="shield-halved">
    Catch governance risks, liquidity traps, and code vulnerabilities before your users deposit
  </Card>

  <Card title="User Protection" icon="user-shield">
    Surface vault health data so users can make informed decisions about their capital
  </Card>
</CardGroup>

**Why teams choose Webacy for vault screening:**

* **7 risk categories, 41 tags** — Covers structure, governance, liquidity, code quality, asset risk, performance, and protocol risk
* **Listing verdicts** — `safe_to_list`, `caution`, `review_required`, `do_not_list` — actionable decisions, not just numbers
* **Sub-500ms responses** — Screen vaults in real-time without blocking your UI
* **6 EVM chains** — ETH, ARB, BASE, OPT, POL, BSC from a single API

***

## Prerequisites

Before implementing vault screening, ensure you have:

* A Webacy API key ([sign up here](https://developers.webacy.co/billing))
* Basic familiarity with REST APIs or the [Webacy SDK](/sdk/installation)
* Your vault listing or portfolio management flow identified for integration points

***

## Screen a Vault Before Listing

Before surfacing a vault to users, check its risk rating and listing verdict.

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

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

  console.log(`Risk Rating: ${vault.riskScore}/100`);
  console.log(`Tier: ${vault.tier}`);
  console.log(`Listing Verdict: ${vault.listingVerdict}`);
  ```

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

  response = requests.get(
      "https://api.webacy.com/vaults/0x0deFfd509197aAD5207d2A55862835b467E8128F",
      params={"chain": "eth"},
      headers={"x-api-key": "YOUR_API_KEY"}
  )
  vault = response.json()
  ```
</CodeGroup>

**Key response fields:**

| Field            | Description                                                            | Action                                  |
| ---------------- | ---------------------------------------------------------------------- | --------------------------------------- |
| `riskScore`      | 0-100 composite rating                                                 | Set your threshold (e.g., >50 = review) |
| `tier`           | `low` / `medium` / `high` / `critical`                                 | Quick categorization                    |
| `listingVerdict` | `safe_to_list` / `caution` / `review_required` / `do_not_list`         | Direct listing decision                 |
| `withdrawalRisk` | `null` / `constrained` / `delayed` / `illiquid` / `locked` / `blocked` | User exit condition                     |
| `risk.issues[]`  | Array of risk tags with severity                                       | Understand what's driving the rating    |

### Listing Verdict Decision Logic

| Verdict           | Action                                                      |
| ----------------- | ----------------------------------------------------------- |
| `safe_to_list`    | Auto-approve for listing                                    |
| `caution`         | List with a risk warning badge                              |
| `review_required` | Queue for manual review before listing                      |
| `do_not_list`     | Block from listing — has blocking risk tags or rating >= 75 |

***

## Monitor High-Risk Vaults

Once vaults are listed, monitor them continuously for changes.

<CodeGroup>
  ```bash cURL theme={null}
  # Get all vaults needing attention, sorted by risk
  curl -X GET "https://api.webacy.com/vaults?attentionNeeded=true&sort=score_desc&pageSize=50" \
    -H "x-api-key: YOUR_API_KEY"
  ```

  ```typescript TypeScript theme={null}
  const response = await fetch(
    'https://api.webacy.com/vaults?attentionNeeded=true&sort=score_desc&pageSize=50',
    { headers: { 'x-api-key': process.env.WEBACY_API_KEY } }
  );
  const { data } = await response.json();

  for (const vault of data) {
    if (vault.tier === 'critical') {
      console.log(`ALERT: ${vault.name} is now critical (${vault.riskScore}/100)`);
    }
  }
  ```

  ```python Python theme={null}
  response = requests.get(
      "https://api.webacy.com/vaults",
      params={"attentionNeeded": "true", "sort": "score_desc", "pageSize": 50},
      headers={"x-api-key": "YOUR_API_KEY"}
  )
  vaults = response.json()["data"]
  ```
</CodeGroup>

**Useful filters for monitoring:**

| Filter                              | Example                   | Use Case                  |
| ----------------------------------- | ------------------------- | ------------------------- |
| `tier=critical`                     | Only critical vaults      | Alert pipeline            |
| `attentionNeeded=true`              | Vaults with state changes | Daily monitoring          |
| `riskFlags=vault-redemption-closed` | Specific risk condition   | Targeted alerts           |
| `chain=eth&minTvl=1000000`          | Chain + TVL threshold     | Portfolio-relevant vaults |

***

## Build a Vault Risk Dashboard

Fetch a paginated list of vaults with risk data for a dashboard view.

<CodeGroup>
  ```bash cURL theme={null}
  # USDC vaults on Ethereum, sorted by TVL
  curl -X GET "https://api.webacy.com/vaults?chain=eth&underlying=USDC&sort=tvl_desc&pageSize=25" \
    -H "x-api-key: YOUR_API_KEY"
  ```

  ```typescript TypeScript theme={null}
  async function fetchVaultDashboard(chain: string, page = 1) {
    const params = new URLSearchParams({
      chain,
      sort: 'tvl_desc',
      pageSize: '25',
      page: String(page),
    });

    const response = await fetch(
      `https://api.webacy.com/vaults?${params}`,
      { headers: { 'x-api-key': process.env.WEBACY_API_KEY } }
    );
    return response.json();
  }

  const dashboard = await fetchVaultDashboard('eth');
  console.log(`Total vaults: ${dashboard.total}`);

  for (const vault of dashboard.data) {
    console.log(`${vault.name} | TVL: $${vault.tvl} | Risk: ${vault.riskScore} | ${vault.tier}`);
  }
  ```

  ```python Python theme={null}
  params = {
      "chain": "eth",
      "underlying": "USDC",
      "sort": "tvl_desc",
      "pageSize": 25,
  }
  response = requests.get(
      "https://api.webacy.com/vaults",
      params=params,
      headers={"x-api-key": "YOUR_API_KEY"}
  )
  dashboard = response.json()
  ```
</CodeGroup>

***

## Complete Integration Workflow

Here's how vault screening fits into a typical platform.

### Vault Listing Flow

```mermaid theme={null}
flowchart TD
    A[New Vault Discovered] --> B{Fetch Risk Rating}
    B --> C{Listing Verdict?}
    C -->|safe_to_list| D[Auto-List Vault]
    C -->|caution| E[List with Risk Badge]
    C -->|review_required| F[Queue for Manual Review]
    C -->|do_not_list| G[Block from Listing]
    D --> H[Add to Monitoring]
    E --> H
    F -->|Approved| H
    H --> I{Daily Check}
    I -->|Tier Changed| J[Alert Team]
    I -->|Still OK| I
```

### Implementation Example

<Accordion title="Full TypeScript Implementation">
  ```typescript theme={null}
  const API_BASE = 'https://api.webacy.com';
  const API_KEY = process.env.WEBACY_API_KEY;

  const headers = { 'x-api-key': API_KEY };

  // Screen a vault before listing
  async function screenVault(address: string, chain: string) {
    const res = await fetch(
      `${API_BASE}/vaults/${address}?chain=${chain}`,
      { headers }
    );
    const vault = await res.json();

    return {
      address,
      chain,
      name: vault.name,
      riskScore: vault.riskScore,
      tier: vault.tier,
      verdict: vault.listingVerdict,
      withdrawalRisk: vault.withdrawalRisk,
      tags: vault.risk?.issues?.flatMap(i => i.tags?.map(t => t.key)) ?? [],
    };
  }

  // Decide listing action based on verdict
  function decideListing(vault: Awaited<ReturnType<typeof screenVault>>) {
    switch (vault.verdict) {
      case 'safe_to_list':
        return { action: 'LIST', badge: null };
      case 'caution':
        return { action: 'LIST', badge: 'risk-warning' };
      case 'review_required':
        return { action: 'REVIEW', badge: 'pending-review' };
      case 'do_not_list':
        return { action: 'BLOCK', badge: null, reason: vault.tags.join(', ') };
    }
  }

  // Monitor all listed vaults
  async function monitorVaults() {
    const res = await fetch(
      `${API_BASE}/vaults?attentionNeeded=true&sort=score_desc&pageSize=100`,
      { headers }
    );
    const { data } = await res.json();

    const alerts = data.filter(v => v.tier === 'critical' || v.tier === 'high');

    for (const vault of alerts) {
      console.log(
        `[${vault.tier.toUpperCase()}] ${vault.name} — ` +
        `Rating: ${vault.riskScore}/100, ` +
        `Verdict: ${vault.listingVerdict}`
      );
    }

    return alerts;
  }

  // Example usage
  const result = await screenVault(
    '0x0deFfd509197aAD5207d2A55862835b467E8128F',
    'eth'
  );
  const decision = decideListing(result);
  console.log(`${result.name}: ${decision.action}`);
  ```
</Accordion>

***

## API Quick Reference

| Endpoint                              | Use Case                       | Response Time |
| ------------------------------------- | ------------------------------ | ------------- |
| `GET /vaults`                         | List all vaults with risk data | \~300ms       |
| `GET /vaults/{address}?chain={chain}` | Full vault risk detail         | \~500ms       |

**Authentication:**

```text theme={null}
Header: x-api-key: YOUR_API_KEY
Base URL: https://api.webacy.com
Supported chains: eth, arb, base, opt, pol, bsc
```

***

## Next Steps

<CardGroup cols={2}>
  <Card title="Vault Risk API" icon="vault" href="/api-reference/vaults">
    Full endpoint reference with all query parameters
  </Card>

  <Card title="Rating Methodology" icon="calculator" href="/api-reference/vault-rating">
    How vault risk ratings are computed — sub-ratings, penalties, and floors
  </Card>

  <Card title="Stablecoin Depeg Monitoring" icon="chart-line" href="/guides/stablecoin-depeg-monitoring">
    Monitor the stablecoins that underlie your vaults
  </Card>

  <Card title="Risk Tags Reference" icon="tags" href="/essentials/risk-tags">
    Complete list of all risk tags and what they mean
  </Card>
</CardGroup>