Skip to main content

​
Overview

V3 is a new, versioned vault risk surface that ships alongside v2. v2 (/api/v2/*) is frozen but fully supported through the deprecation window. New integrations should target V3; existing v2 integrations have time to migrate. This guide is what the v2 Link: rel="deprecation" header will eventually point at. The header itself lands at V3 GA, not in Phase 1 — but the URL needs to resolve before it ships, which is what this page provides. For the response shape, polarity rules, and upstream floor behavior, start with the V3 overview.

​
What’s new in V3

V3 introduces a composite letter grade, per-category risk contributors, a dense criteria taxonomy, and an honest coverage disclosure. The underlying v2 risk envelope is preserved verbatim on every V3 response, so existing v2 consumers can adopt V3 incrementally — read the new fields when ready, ignore them otherwise. See the framework methodology page for the full picture.

​
Versioning contract

V3 commits to a stable contract across four surfaces:
SurfaceMechanism
URL path/api/v2/... and /api/v3/... run in parallel
Response bodyTop-level schema_version field (currently "3.0")
Response headersWebacy-Api-Version, Webacy-Framework-Version, Webacy-Grading-Scheme
Deprecation headersDeprecation, Sunset, and Link per RFC 8594 (land at V3 GA)
The deprecation contract is a 9-month sunset window from V3 GA. Once GA ships, every v2 response will carry:
  • Deprecation: <timestamp> — when v2 was officially deprecated
  • Sunset: <timestamp> — when v2 will stop responding (GA + 9 months)
  • Link: <this URL>; rel="deprecation" — pointer to this migration guide
The deprecation headers are not enabled in Phase 1. They land alongside V3 GA. v2 continues to respond normally in the meantime; the migration window starts when those headers appear, not before.

​
Pin from day one

V3 lets you pin both the framework version and the grading scheme. Both default, but pinning is the contract — clients that don’t pin will silently re-score when a new framework or scheme version ships. 
curl "https://api.webacy.com/api/v3/vaults/0x1234?chain=eth&framework_version=v1&grading_scheme=v1" \
  -H "x-api-key: YOUR_API_KEY"
ParameterDefaultBehavior on unknown value
?framework_version=v1v1400 with { error, supported_versions: ['v1'] }
?grading_scheme=v1v1400 with { error, supported_schemes: ['v1'] }
Pin both from your very first V3 call. When v2 of either ships, you’ll get an explicit 400 instead of a silent score change — and you can roll your client forward on your own schedule. The Webacy-Framework-Version and Webacy-Grading-Scheme response headers echo the resolved pins, so you can confirm what was used to score each response.

​
Endpoint mapping

v2 endpointV3 endpointStatus
GET /api/v2/vaults/:addressGET /api/v3/vaults/:addressAvailable now (Phase 1)
(new in V3)GET /api/v3/frameworkAvailable now (Phase 1)
GET /api/v2/rwa/*GET /api/v3/rwa/*Roadmap (Phase 2A)
The V3 vault detail endpoint requires the same x-api-key header as v2 and consumes a single CU per call (@Billable({ baseCu: 1, name: 'v3-vault-detail' })). The chain query parameter is required (eth | arb | base | opt | pol | bsc); responses include the v2 metadata block verbatim. The framework endpoint is public — no API key, no billing, cacheable for 5 minutes.

​
What stays unchanged in v2

  • All /api/v2/* endpoints continue to respond normally throughout the deprecation window.
  • v2 schemas are frozen — no new fields, no behavior changes.
  • The risk envelope on V3 responses is a verbatim pass-through of the v2 envelope. If you’re already consuming risk.score, risk.overallRisk, risk.issues, or risk.tags from v2, the same code reads them from V3 without modification.
This means you can migrate to V3 incrementally: switch your endpoint, keep your existing risk-envelope handling, and adopt the new composite, categories, and coverage blocks on your own timeline.

​
⚠️ Score polarity for dashboard builders

V3 numeric scores are higher = worse, the same direction as v2 risk.score and risk.overallRisk.If you’re building dashboards from V3 — color scales, sorts, thresholds, alerts — treat higher numbers as worse, not better. The letter grade goes in the conventional direction (A+ is best, F is worst), but the underlying numeric scores are risk magnitudes.This is consistent with v2, which is why we chose this direction. It does mean the V3 numeric scale runs the opposite way from Moody’s, S&P, and similar rating conventions where higher = better. Don’t confuse the two.If you treat V3 scores as “higher = better” by mistake, your dashboard will silently invert risk: high-risk vaults will look safe and low-risk vaults will look dangerous. There is no other gotcha in this migration that comes close to this one in impact — please verify your polarity once before shipping.
The V3 overview has the full worked example (score 64 → C-), including the per-category contributors table with weights. Also note the upstream floor: composite.score = max(framework_composite, upstream_risk). A vault with clean contributors and a high score is being clamped by risk.overallRisk — the clamped_by_upstream: true flag is the visible signal. Surface it.

​
Migration checklist

  • Update your client to call /api/v3/... for new code paths.
  • Add ?framework_version=v1&grading_scheme=v1 to every V3 request.
  • Read Webacy-Framework-Version and Webacy-Grading-Scheme on responses to confirm the resolved pins.
  • Audit dashboards and alerting for score polarity — higher = worse.
  • Display clamped_by_upstream and coverage alongside category scores.
  • Continue consuming risk.* from V3 responses the same way you did from v2; the envelope is identical.
  • When Deprecation and Sunset headers appear on v2 responses (at V3 GA), plan your full cutover before the Sunset date.

Vault Risk V3 Overview

Polarity, upstream floor, versioning contract, and category list.

Framework Methodology

How composite scores are derived and why the framework is API-driven.

Vault Detail (V3)

Full request/response reference for GET /api/v3/vaults/{address}.

Framework Taxonomy

Public framework endpoint — the canonical category and criteria list.