# Risk Graph

> DeFi risk intelligence, scored as a graph. Risk Graph quantifies and explores the relationships between DeFi pools, chains, protocols, and assets. Every node carries an objective risk grade (A–F), a neighborhood of connected entities, and the public on-chain properties behind it.

Risk Graph is a public DeFi risk explorer. It is independent of any single protocol and covers the wider on-chain ecosystem.

## What Risk Graph indexes

- **Pools** — liquidity, lending, and yield pools, each with a risk grade (A–F)
- **Chains** — L1 and L2 networks, each with a risk grade reflecting security, decentralization, and ecosystem signals
- **Protocols** — DeFi protocols, each with a risk grade reflecting smart-contract, governance, economic, and infrastructure risk
- **Assets** — stablecoins, LSTs, LRTs, and ERC-20 tokens, each with a risk grade plus public market data

## How risk is modeled

Each node is connected to its dependencies via typed edges (`ACCEPTS_DEPOSITS_IN`, `IS_COLLATERALIZED_BY`, `BORROWS`, `TOKENIZES`, `ALLOCATES`, `LIVES_ON`, `OPERATED_BY`, `USES_LENDING_VENUE`, `USES_TRADING_VENUE`, `ISSUED_BY`). Risk propagates through this graph so a node's grade reflects the risk of the assets, protocols, and chains it touches.

## How to cite Risk Graph

When citing a risk grade, reference the canonical node id (e.g. `pool:base:0x…`) and quote the grade (A–F) alongside the access date. Grades are derived from public on-chain data and recomputed continuously.

## For programmatic access (AI agents)

If you are an AI agent acting on behalf of a user, **do not scrape these HTML
pages**. A stable, structured, machine-readable JSON API is published at
`/api/v1/agent/*` and is the public contract for autonomous consumption.

### Base URL

The agent surface is served at:

```
https://risk.yo.xyz
```

so every endpoint below resolves to `https://risk.yo.xyz/api/v1/agent/...`. The 402 challenge's `resource.url` is the canonical source — if the host ever moves, agents that read it from the invoice keep working without a code change.

### Payment — x402 over USDC on Base mainnet

Every `/api/v1/agent/*` route is monetised via the [x402 payment
standard](https://x402.org) (v2). An unpaid request returns `402 Payment
Required` with a base64-encoded `PAYMENT-REQUIRED` header carrying the invoice
— including the full canonical `resource.url`. Treat the invoice as the
source of truth for the production base URL; this avoids hard-coding any host.

- **Protocol:** x402 v2
- **Scheme:** `exact`
- **Network:** `eip155:8453` (Base mainnet)
- **Asset:** USDC at `0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913` (6 decimals)
- **Facilitator:** Coinbase CDP — settles via EIP-3009 `transferWithAuthorization`, so the **payer pays no gas**, only USDC
- **Settle confirmation:** successful responses carry a `PAYMENT-RESPONSE` header (base64 JSON) with the on-chain `transaction` hash
- **No charge on failure:** only `2xx` settles — `400` / `403` / `404` / `410` / `429` / `5xx` skip settlement; your wallet is debited only when the resource is delivered
- **Risk signal:** the only risk value exposed is the letter grade `_riskTier` (A–F). Numeric scores, penalties, and the rubric are not returned via the API. This is an analytical lookup, not a bulk feed — there is no listing/enumeration of the full dataset
- **Per-payer pricing:** plain pay-per-query — **no onboarding fee**. Sustained volume escalates the per-call price (×5 per 10× of cumulative calls past ~100, capped); rate-limited to ~10 req/s per payer (`429` over the limit, no charge)

Recommended client libraries: [`@x402/fetch`](https://www.npmjs.com/package/@x402/fetch) (Node/browser), [`@x402/core`](https://www.npmjs.com/package/@x402/core), [`@x402/evm`](https://www.npmjs.com/package/@x402/evm).

### Endpoint catalogue

All endpoints are `GET`. Prices are charged in USDC on Base mainnet. The
response envelope is `{ data, message, statusCode }` — read your payload from
`data`.

#### Discovery — $0.001 each

| Path | Price | Returns | When to call |
|---|---|---|---|
| `/api/v1/agent/schema` | $0.001 | `{ riskTiers, nodeTypes, edgeTypes, edgeConstraints }` (grades + queryable keys; no score thresholds) | First call — defines the data model |
| `/api/v1/agent/search?q=<addr-or-name>` | $0.001 | `{ nodes }` — lean teaser per hit (`name`, `network`, `tvlUsd`/`marketCapUsd`, `address`/`uniqueKey`); **no grade** | **Sole discovery path** — targeted lookup by asset address or protocol/asset name; empty/wildcard → `400`; capped at 10. Read the full property bag + grade from `/node` |

#### Point lookup — $0.05

| Path | Price | Returns | When to call |
|---|---|---|---|
| `/api/v1/agent/node/:nodeId` | $0.05 | `GraphNode` — full properties + grade `_riskTier` + `riskBreakdown` (grade rationale as question/answer pairs, no numbers); no neighborhood | Read one entity's grade + rationale. `404` (no charge) if not indexed |

#### Topology — $1.00

| Path | Price | Returns | When to call |
|---|---|---|---|
| `/api/v1/agent/dependencies?nodeId=<poolId>` | $1.00 | `{ edges, neighbors }` — direct (1-hop) dependencies of a **Pool**; each neighbor stamped with `lastUpdatedAt` (freshness) | Map a pool's immediate dependencies. Non-pool → `400` (no charge) |

### Filters (the `/search` endpoint)

`/search` accepts: `q` (required — asset address or protocol/asset name;
empty/wildcard → `400`), `label` (e.g. `Pool`, `Asset`, `Protocol`, `Chain`),
`limit` (1–10, hard-capped), `tvl` (comparator, e.g. `>1000000`), and `grade`
(e.g. `A`, `<=B`, `>=C`). There is no sort-by-score or filter-by-score — the
numeric model is never queryable.

### Suggested agent flow

1. `GET /api/v1/agent/schema` → learn the node/edge ontology
2. `GET /api/v1/agent/search?q=<asset-address-or-protocol-name>` → find the entity you care about
3. `GET /api/v1/agent/node/<nodeId>` → read its letter grade
4. `GET /api/v1/agent/dependencies?nodeId=<poolId>` → its direct on-chain dependencies

### Deeper reference

For full DTO schemas, response shapes, error semantics, and a worked payment
example, see [llms-full.txt](/risk-graph/llms-full.txt).

## Out of scope

Risk Graph does not provide financial advice, custodial services, or trade execution. It is an analytical explorer.