Implement a Risk Rating in Your UI

Your users see a vault or tokenized asset in your app. They have no way to tell a well-run vault from a risky one, and building your own scoring model is a project you don’t want to own. This guide shows you how to surface Webacy’s graded A+ to F rating instead: call one v3 endpoint, pull a handful of fields, and render a badge your users can trust.

Why Surface a Graded Rating

Ship a Rating, Not a Model

Render Webacy’s graded A+ to F composite instead of building and maintaining your own scoring model

Always Current

Poll on a cadence and the grade reflects live governance, liquidity, and code risk, not a one-time score

Explainable

A per-category breakdown shows users exactly what is driving the grade

Why teams choose Webacy for ratings:

Graded output: an A+-F composite grade, a star rating, and a 0-100 score in one response
Category breakdown: per-category scores so you can show what is driving the grade
Same shape for vaults and RWAs: one integration renders both /v3/vaults and /v3/rwa
Fail-closed: a freshness timestamp so you can hide stale grades instead of showing them

Prerequisites

Before implementing a rating, ensure you have:

A Webacy API key (sign up here)
Basic familiarity with REST APIs or the Webacy SDK
A vault or RWA contract address and its chain, plus the UI surface you want to render into

Step 1: Call the v3 Endpoint

Both /v3/vaults/{address} and /v3/rwa/{address} return the same graded shape. Call /v3/vaults for an ERC-4626 vault, and /v3/rwa for a tokenized real-world asset or a stablecoin (the RWA endpoint covers both). chain is required.

curl -X GET "https://api.webacy.com/v3/vaults/0x0deFfd509197aAD5207d2A55862835b467E8128F?chain=eth" \
  -H "x-api-key: YOUR_API_KEY"

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

console.log(`Grade: ${rating.composite.grade} (${rating.composite.stars} stars)`);
console.log(`Score: ${rating.composite.score}/100, higher is worse`);

import requests

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

composite.score and every categories.*.score run 0-100 where higher means more risk: A+ maps to a score near 0, F maps to a score near 100. This is the opposite of a health or safety score. When you color, sort, or threshold by this number, higher must render as worse.

To rate an RWA or a stablecoin instead, swap the path segment. Everything else is identical:

curl -X GET "https://api.webacy.com/v3/rwa/{rwaAddress}?chain=eth" \
  -H "x-api-key: YOUR_API_KEY"

Step 2: Pull the Fields That Matter

Read the response into a small view model. These are the fields worth rendering:

Field	What it drives in the UI
`composite.grade`	The headline letter badge (`A+` … `F`)
`composite.stars`	A 1 to 5 rating derived from the grade (optional secondary signal)
`composite.score`	Tooltip / numeric label (0-100, higher = more risk)
`categories.*.score`	The “what’s driving the grade” breakdown, one row per category
`coverage.live_criteria` / `coverage.total_criteria`	A “based on X of Y checks” disclosure
`metadata.last_scored_at`	An “updated ” label and your freshness / stale handling

type RatingViewModel =
  | { ok: false; reason: string }
  | {
      ok: true;
      grade: string;
      stars: number;
      score: number; // 0-100, higher = MORE risk
      color: string;
      categories: { name: string; score: number }[];
      coverage: string;
      updatedAt: string;
    };

// Map on the first letter so every band (A+, A, A-, … F) resolves without gaps.
function gradeColor(grade: string): string {
  switch (grade[0]) {
    case 'A': return '#0d9c4a';
    case 'B': return '#8bc34a';
    case 'C': return '#ffc107';
    case 'D': return '#ff9800';
    default:  return '#b71c1c'; // F
  }
}

async function getRatingViewModel(
  kind: 'vaults' | 'rwa',
  address: string,
  chain: string,
): Promise<RatingViewModel> {
  const res = await fetch(
    `https://api.webacy.com/v3/${kind}/${address}?chain=${chain}`,
    { headers: { 'x-api-key': process.env.WEBACY_API_KEY! } },
  );

  // Fail closed: never render an errored or missing rating as if it were good.
  if (!res.ok) return { ok: false, reason: `rating unavailable (${res.status})` };

  const { composite, categories, coverage, metadata } = await res.json();

  return {
    ok: true,
    grade: composite.grade,
    stars: composite.stars,
    score: composite.score,
    color: gradeColor(composite.grade),
    categories: Object.entries(categories).map(([name, c]: [string, any]) => ({
      name,
      score: c.score,
    })),
    coverage: `${coverage.live_criteria}/${coverage.total_criteria} checks live`,
    updatedAt: metadata.last_scored_at,
  };
}

Step 3: Render the Badge

The badge is the small pill your users see next to the asset: the letter grade tinted by risk (green for the A band through red for F), with the numeric score in the tooltip. This component takes the view model from Step 2 and renders that pill, showing a neutral “Rating unavailable” state when the rating could not be loaded.

function RatingBadge({ vm }: { vm: RatingViewModel }) {
  if (!vm.ok) {
    return <span className="rating-badge rating-badge--unknown">Rating unavailable</span>;
  }

  return (
    <span
      className="rating-badge"
      style={{ background: vm.color }}
      title={`Risk score ${vm.score}/100 (higher = more risk) · ${vm.coverage} · updated ${vm.updatedAt}`}
    >
      <strong>{vm.grade}</strong>
    </span>
  );
}

Plain-HTML equivalent, if you’re not on React:

<span class="rating-badge" style="background:#0d9c4a"
      title="Risk score 12/100 (higher = more risk) · 38/40 checks live">
  <strong>A</strong>
</span>

Rendered in a dark UI, the badge and its sub-scores look like this:

Example vault rating card with an A grade, a 6.1 out of 100 risk score, and sub-score risk bars

Example stablecoin rating card with an A+ grade, a 3.2 out of 100 risk score, and risk-driver bars

Step 4: Show What’s Driving the Grade

Use categories.* for an expandable breakdown, sorted worst-first (higher score = more risk):

function CategoryBreakdown({ categories }: { categories: { name: string; score: number }[] }) {
  const sorted = [...categories].sort((a, b) => b.score - a.score); // worst first
  return (
    <ul className="rating-breakdown">
      {sorted.map((c) => (
        <li key={c.name}>
          <span>{c.name}</span>
          <meter min={0} max={100} low={40} high={70} optimum={0} value={c.score} />
          <span>{c.score}/100</span>
        </li>
      ))}
    </ul>
  );
}

For a fuller view, the same rating powers a detailed breakdown: framework categories, risk flags, and curator terms.

Example detailed vault rating card with a framework categories table, risk flags, and curator and protocol terms

Handle Freshness and Failures

A rating you can’t vouch for is worse than no rating. The v3 detail endpoints do not return a top-level stale flag, use metadata.last_scored_at to decide whether the grade is current enough to show.

Render an explicit “rating unavailable” state, not a stale grade, whenever the call fails or metadata.last_scored_at is older than your freshness policy. Treat missing or stale data as unknown risk, never as a pass. See hard-gating and fail behavior.

Complete Example

Full React Implementation

import { useEffect, useState } from 'react';

// See Step 2 for RatingViewModel, gradeColor, and getRatingViewModel.

function VaultRating({ address, chain }: { address: string; chain: string }) {
  const [vm, setVm] = useState<RatingViewModel | null>(null);

  useEffect(() => {
    getRatingViewModel('vaults', address, chain).then(setVm);
  }, [address, chain]);

  if (!vm) return <span className="rating-badge rating-badge--loading">…</span>;
  if (!vm.ok) return <span className="rating-badge rating-badge--unknown">Rating unavailable</span>;

  return (
    <div className="rating">
      <span className="rating-badge" style={{ background: vm.color }} title={`Risk score ${vm.score}/100 (higher = more risk)`}>
        <strong>{vm.grade}</strong>
      </span>
      <small>{vm.coverage} · updated {vm.updatedAt}</small>
      <ul className="rating-breakdown">
        {[...vm.categories].sort((a, b) => b.score - a.score).map((c) => (
          <li key={c.name}>
            <span>{c.name}</span>
            <meter min={0} max={100} low={40} high={70} optimum={0} value={c.score} />
            <span>{c.score}/100</span>
          </li>
        ))}
      </ul>
    </div>
  );
}

API Quick Reference

Endpoint	Use Case
`GET /v3/vaults/{address}?chain={chain}`	Graded vault rating (grade, stars, score, categories, coverage)
`GET /v3/rwa/{address}?chain={chain}`	Graded RWA rating (same shape as vaults)

Authentication:

Header: x-api-key: YOUR_API_KEY
Base URL: https://api.webacy.com

Next Steps

Ongoing Risk Monitoring

Poll the rating on a cadence and alert when the grade or tier changes

New Asset Due Diligence

Run the full pre-allocation workflow before you surface an asset

Vault Risk (V3) API

Full endpoint reference for the graded vault rating

RWA Risk (V3) API

Full endpoint reference for the graded RWA rating

Getting Started

Risk Ratings, Scoring, and Documentation

SDK

Integrations

Essentials

Glossary

Implement a Risk Rating in Your UI

Why Surface a Graded Rating

Ship a Rating, Not a Model

Always Current

Explainable

Prerequisites

Step 1: Call the v3 Endpoint

Step 2: Pull the Fields That Matter

Step 3: Render the Badge

Step 4: Show What’s Driving the Grade

Handle Freshness and Failures

Complete Example

API Quick Reference

Next Steps

Ongoing Risk Monitoring

New Asset Due Diligence

Vault Risk (V3) API

RWA Risk (V3) API

​Why Surface a Graded Rating

Ship a Rating, Not a Model

Always Current

Explainable

​Prerequisites

​Step 1: Call the v3 Endpoint

​Step 2: Pull the Fields That Matter

​Step 3: Render the Badge

​Step 4: Show What’s Driving the Grade

​Handle Freshness and Failures

​Complete Example

​API Quick Reference

​Next Steps

Ongoing Risk Monitoring

New Asset Due Diligence

Vault Risk (V3) API

RWA Risk (V3) API

Why Surface a Graded Rating

Prerequisites

Step 1: Call the v3 Endpoint

Step 2: Pull the Fields That Matter

Step 3: Render the Badge

Step 4: Show What’s Driving the Grade

Handle Freshness and Failures

Complete Example

API Quick Reference

Next Steps