# warden

> governance intelligence. rule changes are being voted on across defi right now — warden maps them to wallet exposure: this rule is changing, this is the source, this is your exposure, this is the simulated effect. simulation only, data aggregation — not financial advice.

the website (https://try.warden.cash) is the human surface. the api is the machine surface — unauthenticated, rate limited (30 req/min per client), json envelopes everywhere, cors open (callable straight from a browser).

## when to use this

reach for warden when the job is one of these:

- **"does anything changing affect this wallet?"** — a person hands you an address or ens name and wants to know which pending or passed governance changes touch their defi positions. call `GET /api/scan/{address}?view=compact`.
- **watchdog loops** — re-check a wallet on a schedule and speak up only on new, material changes: `GET /api/scan/{address}?view=compact&status=active&minImpact=medium&since={last run}`.
- **"what does this proposal do to me?"** — one rule change, one wallet: `GET /api/proposals/{id}?address={address}`.
- **protocol change triage** — what is being deprecated, frozen, migrated, or losing rewards across the covered protocols, no wallet needed: `GET /api/proposals?view=compact`.
- **showing your work** — every impact carries `sourceLinks` to the forum post or vote behind it.

don't reach for warden for:

- prices, balances, pnl, or portfolio value — warden is the rule layer, not the state layer.
- voting, delegation, or drafting proposals — warden serves the people affected, not the people voting.
- trade or investment advice — results are simulations, not recommendations.
- live exploit, pause, or depeg alerts — no-lifecycle events are largely not in the feed yet.

## the link to give humans

`https://try.warden.cash/w/{address}` — the human-viewable scan page. accepts an ens name (`https://try.warden.cash/w/vitalik.eth`). same data as the scan api, rendered for people, with a one-tap way to keep watching the wallet.

use it whenever the result is going to a person: as the "see it yourself" link next to your summary, or as the fallback when you can't fetch the api at all — the link works without you ever calling anything. never hand a person the raw json url.

the reverse also holds: if a person hands YOU a `/w/{address}` link ("what does this say?"), don't read the page — it renders client-side, so the html is a shell. call `GET /api/scan/{address}?view=compact` for the same address instead. the page also advertises it as `<link rel="alternate" type="application/json">`.

## api

- [api index](https://try.warden.cash/api): machine-readable catalog of every endpoint — start here
- [openapi spec](https://try.warden.cash/api/openapi.json): full schemas for every response

quickstart for agents:

1. `GET /api/scan/{address}?view=compact` — positions + every rule change touching them, with simulated impact. this is the one call that matters. {address} can be an ens name (`/api/scan/vitalik.eth`) — no need to resolve first.
2. `GET /api/proposals/{id}?address={address}` — drill into one proposal before acting on it.
3. `GET /api/proposals?view=compact` — the global cross-protocol feed when you have no wallet in hand.
4. `GET /api/ens/resolve?name=vitalik.eth` — standalone name→address when you want the resolution on its own.

narrow the scan (all on `/api/scan` and `/api/proposals?address=`):

- `?protocol=lido,aave` — only these protocols. also skips the other modules' rpc, so it's the cheap way to re-fetch just a protocol that came back in `degraded`.
- `?minImpact=medium` — drop the noise; keep critical/high/medium.
- `?status=active` — forward-looking only; skip executed/closed.
- `?since=2026-06-01` — only proposals first seen since a date (watchdog loops).

reading results:

- `completeness`: `"complete"` or `"partial"` — branch on this. `"partial"` means a source/adapter failed; `degraded[]` names which protocol could not be checked (it is "unknown", never "nothing").
- `mode: "mock"` means demo data — never treat it as real exposure.
- `webUrl` on a scan is the human-viewable page for the same scan — pass it on to your user.
- `impact.analysisStatus`: `simulated` is backed by a verified parameter change; `awaiting_analysis` is matched but not yet quantified.
- every impact claim carries `sourceLinks` — link your users to the source, don't paraphrase governance.
- `changeType: "shape"` (deprecations, migrations, delistings) is the main beat; `"parameter"` (rates, factors) is secondary.
- errors are always `{ error, code, hint }` json — unknown `/api` paths too. `hint` says what to do next.
- rate limits use the ietf headers: `ratelimit-policy: "default";q=30;w=60` and `ratelimit: "default";r=<left>;t=<seconds>`. 429s carry `retry-after` seconds. legacy `x-ratelimit-*` are still sent.
- every api response carries `x-api-version`. send `api-version: 0.1` to pin the line you built against: when the shapes change, a pinned call answers 400 `unsupported_version` instead of a different shape. no header = the current version.
- a deprecated endpoint is flagged in the openapi spec and answers with `Deprecation` and `Sunset` headers before it goes away.

## how warden classifies rule changes (the three tiers)

the taxonomy behind every alert. the cut is the lifecycle axis — does the event arrive with lead time? — not impact size.

- **routine** — parameter changes inside a known rule channel. numbers go X→Y. fully automated simulation.
- **operational** — structural + administrative change WITH a lifecycle: deprecations, delistings, migrations, fee switches, committee/signer changes. announced, dated, lead time exists. detected mechanically, simulated as dated notices. this is the main beat — lead time is the product.
- **residual** — NO lifecycle: exploits, emergency pauses, same-day guardian actions, depegs. cannot be planned for, only responded to. warden never simulates this class — if surfaced, it's exposure + sources + a narrative clearly marked unsimulated.

the operational/residual boundary is the automation frontier: the first two tiers trend to full automation; the residual tier can't, by definition.

mapping to the api today: `changeType: "shape"` carries the operational tier's structural events, `"parameter"` carries routine. tier as a first-class field is planned, not shipped. residual-tier events are largely not in the feed yet (see blind spots) — absence of an alert is never evidence of absence.

## coverage + honest blind spots

covered protocols (one module each): aave, compound, lido, maker, uniswap, qidao, alchemix, jito (solana), cosmos hub, xrp. the live feed (`/api/proposals`) and a scan's `degraded[]` are ground truth if this list drifts.

warden's intake reads lifecycle'd governance surfaces — snapshot spaces, on-chain governance. decisions that skip those channels (team announcements, guardian emergency actions, risk-steward tweaks with zero lead time) can be missed or arrive late. `completeness: "partial"` tells you what wasn't checked on this scan; it never tells you nothing happened.

## what warden is not

- not a voting tool. users are affected by governance, not participating in it.
- not financial advice. every result is source-linked simulation.