> ## 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. # Migrating from v2 to V3 > Migrate your client from the v2 Webacy API to V3 — what changed, what stayed compatible, how to pin versions, and the deprecation timeline for v2. ## Overview V3 is a new, versioned vault risk surface that ships alongside v2. v2 endpoints have **no version prefix** — they live at unversioned root paths such as `/vaults/{address}` and `/rwa/*` — and are **frozen but fully supported** through the deprecation window. New integrations should target V3 (`/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 at launch — 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](/api-reference/vault-risk-v3/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](/api-reference/vault-risk-v3/framework-methodology) page for the full picture. *** ## Versioning contract V3 commits to a stable contract across four surfaces: | Surface | Mechanism | | ------------------- | -------------------------------------------------------------------------------------------------------------------------- | | URL path | v2 has no version prefix (e.g. `/vaults/{address}`); v3 uses a `/v3/` prefix (e.g. `/v3/vaults/{address}`). Never `/api/`. | | Response body | Top-level `schema_version` field (currently `"3.0"`) | | Response headers | `Webacy-Api-Version`, `Webacy-Framework-Version`, `Webacy-Grading-Scheme` | | Deprecation headers | `Deprecation`, `Sunset`, and `Link` per [RFC 8594](https://www.rfc-editor.org/rfc/rfc8594) (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: ` — when v2 was officially deprecated * `Sunset: ` — when v2 will stop responding (GA + 9 months) * `Link: ; rel="deprecation"` — pointer to this migration guide **The deprecation headers are not enabled at launch.** 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. ```bash theme={null} curl "https://api.webacy.com/v3/vaults/0x1234?chain=eth&framework_version=v1&grading_scheme=v2" \ -H "x-api-key: YOUR_API_KEY" ``` | Parameter | Default | Behavior on unknown value | | ----------------------- | ------- | ------------------------------------------------------- | | `?framework_version=v1` | `v1` | `400` with `{ error, supported_versions: ['v1'] }` | | `?grading_scheme=v2` | `v2` | `400` with `{ error, supported_schemes: ['v1', 'v2'] }` | Pin both from your very first V3 call. The grade scale now defaults to `v2` (the standard 11-band risk scale); `v1` is the frozen legacy scale and stays pinnable via `?grading_scheme=v1`. When a newer version of either the framework or the grading scheme ships, a pinned client gets 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 endpoint | V3 endpoint | Status | | ----------------------- | ----------------------------------------------------------------------------------- | ------------- | | `GET /vaults/{address}` | [`GET /v3/vaults/{address}`](/api-reference/vault-risk-v3/get-vault-risk-detail-v3) | Available now | | *(new in V3)* | [`GET /v3/framework`](/api-reference/vault-risk-v3/get-framework) | Available now | | `GET /rwa/*` | `GET /v3/rwa/*` | Planned | 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 and vault v3 covers **9 chains** — `eth`, `arb`, `base`, `opt`, `pol`, `bsc`, `avax`, `gnosis`, `sol`. Any other value returns `400 "Invalid chain"`, even if accepted by a shared parameter enum. 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 v2 endpoints (unversioned root paths) 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 traditional credit-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](/api-reference/vault-risk-v3/v3-overview#score-polarity) has the full worked example (`score 64 → C-`), including the per-category contributors table with weights. Also note the [upstream floor](/api-reference/vault-risk-v3/v3-overview#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 `/v3/...` for new code paths. * Add `?framework_version=v1&grading_scheme=v2` 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. *** ## Related resources Polarity, upstream floor, versioning contract, and category list. How composite scores are derived and why the framework is API-driven. Full request/response reference for `GET /v3/vaults/{address}`. Public framework endpoint — the canonical category and criteria list.