# Risk Graph — Full Agent Reference

This is the deep reference for AI agents and programmatic clients consuming
Risk Graph's paid `/api/v1/agent/*` API. For the short overview and endpoint
catalogue, see [llms.txt](/risk-graph/llms.txt).

Risk Graph is an **analytical explorer**: it scores DeFi entities (pools,
assets, protocols, chains) and exposes an objective **letter grade** per entity.
It is deliberately **not** a bulk data feed — there is no listing, enumeration,
or full-dataset export, and the underlying scoring model is not fetchable. You
look up specific assets/protocols you already know and read their grade.

> **Stability:** `/api/v1/agent/*` is versioned via the `/v1` segment. Breaking
> changes ship as `/v2`. Prices and response shapes are stable within a major
> version; price changes are announced before they take effect.

---

## 0. Base URL

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

Every endpoint below resolves to `https://risk.yo.xyz/api/v1/agent/...`. Prefer the `resource.url` field from the 402 challenge as the canonical source — if the host ever changes, agents reading from the invoice keep working without a code update.

---

## 1. Payment protocol — x402 v2

Every `/api/v1/agent/*` route is monetised via the
[x402 payment standard](https://x402.org) (version 2). The unpaid request
returns `402 Payment Required`; the paid retry returns the resource and a
settlement receipt.

### 1.1 Network and asset

| Field | Value |
|---|---|
| Protocol version | `2` |
| Scheme | `exact` |
| Network | `eip155:8453` (Base mainnet) |
| Asset | USDC at `0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913` |
| Asset decimals | `6` |
| Settlement | EIP-3009 `transferWithAuthorization` via Coinbase CDP facilitator — the **payer pays no gas**, only USDC |

Amounts in the invoice are USDC atomic units (six decimals). `"1000"` = `$0.001`,
`"50000"` = `$0.05`, `"1000000"` = `$1.00`.

### 1.2 The 402 handshake

**Step 1 — unpaid request:**

```http
GET /api/v1/agent/node/pool:base:0x8eff…  HTTP/1.1
Host: risk.yo.xyz
Accept: application/json
```

**Step 2 — server responds with the invoice.** The body is empty; the invoice
lives in the `PAYMENT-REQUIRED` header as base64-encoded JSON:

```http
HTTP/1.1 402 Payment Required
PAYMENT-REQUIRED: eyJ4NDAyVmVyc2lvbiI6Mi…
```

Decoded:

```json
{
  "x402Version": 2,
  "error": "Payment required",
  "resource": {
    "url": "https://risk.yo.xyz/api/v1/agent/node/pool:base:0x8eff…",
    "description": "Single node — properties + risk grade only (no neighborhood)",
    "mimeType": ""
  },
  "accepts": [
    {
      "scheme": "exact",
      "network": "eip155:8453",
      "amount": "50000",
      "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
      "payTo": "0x<recipient>",
      "maxTimeoutSeconds": 300,
      "extra": { "name": "USD Coin", "version": "2" }
    }
  ]
}
```

`resource.url` is the canonical, self-describing URL — use it instead of
hard-coding any host.

> **Note — the invoice amount can vary by payer.** The price is resolved per
> request (see [§5 Per-payer economics](#5-per-payer-economics)): heavy
> cumulative usage escalates the price (there is **no** onboarding fee). Always
> sign the amount in the invoice you receive; if the amount changed since a prior
> call, the server re-issues a `402` with the correct amount.

**Step 3 — sign the payment** (EIP-3009 `transferWithAuthorization` over USDC)
and retry the same request with an `X-PAYMENT` header. Use a client library
([`@x402/fetch`](https://www.npmjs.com/package/@x402/fetch),
[`@x402/core`](https://www.npmjs.com/package/@x402/core),
[`@x402/evm`](https://www.npmjs.com/package/@x402/evm)) — these handle the
signature for you.

**Step 4 — server returns the resource** with a `PAYMENT-RESPONSE` header
proving settlement:

```http
HTTP/1.1 200 OK
PAYMENT-RESPONSE: eyJzdWNjZXNzIjp0cnVlLCJwYXllciI6IjB4…
Content-Type: application/json

{ "data": { … }, "message": "OK", "statusCode": 200 }
```

The `transaction` field in the decoded receipt is the on-chain Base mainnet
transaction hash — verifiable on [Basescan](https://basescan.org).

### 1.3 No-charge guarantee on failure

The paywall settles **after** the handler responds, and **only on `2xx`
responses**. Any rejection — `400` (bad query), `403` (provenance), `404`
(unknown id or removed endpoint), `429` (rate limit), `5xx` — returns **no
`PAYMENT-RESPONSE` header and no on-chain settlement**. So the point lookups are
safe to probe: a `/node` or `/dependencies` miss returns `404` and is free.
`/search` is the exception — it always settles, **including a zero-result query**
(`200` with an empty `nodes` array), because the targeted scan is the billable
work. Spend `$0.05`+ point lookups only on ids you already hold.

---

## 2. The only risk signal: letter grade

The single risk signal exposed on this surface is the letter grade **`_riskTier`**
(`A` safest → `F` riskiest), present on the `properties` of every node returned
by `/node` and `/dependencies`. (The `/search` teaser is leaner and **omits** the
grade — read it from `/node`.) `/node` additionally returns **`riskBreakdown`**:
the grade's rationale as plain `{ question, answer }` pairs. Numeric scores,
penalties, composites, the scoring rubric, and the grade score-thresholds are
**intentionally not provided** anywhere — in any payload, error, or the schema.
Do not present or infer a numeric risk score; quote the grade.

```ts
type NodeId = string;                              // e.g. "pool:base:0x8eff…"
type NodeLabel = "Pool" | "Asset" | "Protocol" | "Chain";
type PropertyValue = string | number | boolean | null;
type RiskFactor = { question: string; answer: string };   // one scrubbed scorecard line

interface GraphNode {
  id: NodeId;
  labels: NodeLabel[];
  properties: Record<string, PropertyValue> & {
    _riskTier?: string;                               // letter grade A–F (on /node + /dependencies; absent on /search teasers)
    riskBreakdown?: RiskFactor[];                     // grade rationale (Q&A only) — on /node
    lastUpdatedAt?: string;                           // ISO freshness stamp — on /dependencies neighbors
  };                                                  // allow-listed public fields per label; no numeric `_risk*`, no rubric inputs (`derived*`, `_override_*`, peg/backing), no internal/infra fields
}

interface GraphEdge {
  type: string;                                      // e.g. "ACCEPTS_DEPOSITS_IN", "BACKED_BY"
  sourceId: NodeId;
  targetId: NodeId;
  properties: Record<string, PropertyValue>;
}
```

`NodeId` follows a deterministic convention:
`<label>:<chain-or-namespace>:<address-or-slug>` — e.g.
`pool:base:0x8effa741061aaa2d8a5012a9b09a2d31d8b628d7`.

---

## 3. Response envelope

Every response is wrapped:

```json
{ "data": <payload>, "message": "OK", "statusCode": 200 }
```

Read your payload from `data`. Paid responses are marked `Cache-Control:
private` so shared caches can't replay them — cache locally if you need to.

---

## 4. Endpoint reference

All endpoints are `GET`. Four paid endpoints; everything else is removed.

### 4.1 `GET /api/v1/agent/schema` — $0.001

The data-model declaration — node labels, their queryable properties, edge
types, and the grade letters. **Call this first.** Numeric score thresholds are
not included.

### 4.2 `GET /api/v1/agent/search` — $0.001 — **the sole discovery path**

Targeted lookup. You must pass a concrete **asset address** or **protocol/asset
name**; empty and wildcard queries are rejected (`400`). Results are
**hard-capped at 10**. There is no way to list or page the full dataset.

Each hit is a **lean teaser**, not the full node: identity (`id`, `labels`) plus
`name`, `network`, a `$` size (`tvlUsd` for real pools, `marketCapUsd` for
LST/token nodes), and an on-chain handle (`address` or Morpho `uniqueKey`). The
**grade, `riskBreakdown`, and full property bag live on `/node`** — `/search` and
`/node` are deliberately not interchangeable.

| Param | Type | Required | Notes |
|---|---|---|---|
| `q` | string | yes | asset address or protocol/asset name; no `*`/`%` wildcards |
| `label` | `NodeLabel` | no | restrict to one label |
| `limit` | int 1–10 | no | default `10`, capped at `10` |
| `tvl` | string | no | comparator filter, e.g. `>1000000` or `<5e8` |
| `grade` | string | no | grade comparator over A–F, e.g. `A`, `<=B`, `>=C` |

```ts
data: { nodes: GraphNode[] }   // lean teaser per hit: id, labels + { name, network, tvlUsd | marketCapUsd, address | uniqueKey }. No grade, no riskBreakdown, no edges, no scores.
```

### 4.3 `GET /api/v1/agent/node/:nodeId` — $0.05

A single node's full public properties + the grade `_riskTier` + **`riskBreakdown`**
— the grade's rationale as plain `{ question, answer }` pairs (no numbers,
penalties, or rubric). For a promoted `default` pool (e.g. wstETH, sUSDe) that
reports no value-locked figure, the `$` size surfaces as `marketCapUsd` (its
token market cap), never relabeled as `tvlUsd`. No edges or neighbors —
relationship data is available only via `/dependencies`. Returns `404` (no
charge) if the node isn't indexed.

```ts
data: GraphNode   // properties carries _riskTier + riskBreakdown: { question, answer }[]
```

### 4.4 `GET /api/v1/agent/dependencies` — $1.00 — **the sole topology path**

The direct (1-hop) dependencies of a **Pool** — its immediate neighbors and the
edge type to each. Pools only: a non-pool target returns `400` (no charge).
There is no multi-hop traversal. Each neighbor is stamped with **`lastUpdatedAt`**
(ISO timestamp of its last scoring) so you can judge how fresh this view is.

| Param | Type | Required | Notes |
|---|---|---|---|
| `nodeId` | NodeId | yes | a Pool node id |

```ts
data: { edges: GraphEdge[]; neighbors: GraphNode[] }   // each neighbor's properties carries lastUpdatedAt (freshness)
```

> Provenance: `/dependencies` is intended for pools you surfaced via your own
> prior `/search`. See [§5](#5-per-payer-economics).

---

## 5. Per-payer economics

Your identity is the **payer EVM address** recovered from the signed payment.
Pricing and limits are keyed to it.

- **No onboarding fee.** Every endpoint is plain pay-per-query from the first
  call — there is no signup, held balance, or custody.
- **Escalating price.** Sustained high volume from a single payer gets
  progressively more expensive — ×5 per order of magnitude of cumulative settled
  calls beyond the first ~100. Individual lookups stay cheap; bulk extraction
  does not.
- **How pricing surfaces.** Pricing is keyed to the payer address, which only
  appears once the payment is signed — so the *first* (header-less) `402` always
  quotes the base price. When your escalated price is higher, the server
  re-issues a `402` with the corrected amount before settling (one extra
  round-trip); always sign the amount in the invoice you receive.
- **Rate limit.** ~10 requests/second per payer. Over the limit returns `429`
  with a `Retry-After` header (no charge).
- **Provenance.** `/dependencies` is intended for pools you surfaced through your
  own `/search`. Requesting topology for an id you never searched may be
  rejected with `403` (no charge).

---

## 6. Errors

| Status | Meaning | Charged? |
|---|---|---|
| `200` | success — `PAYMENT-RESPONSE` header present | yes |
| `400` | invalid query (e.g. empty/wildcard search, non-pool dependencies) | no |
| `402` | unpaid — `PAYMENT-REQUIRED` header present | no |
| `403` | provenance — dependencies on an id you didn't surface | no |
| `404` | point-lookup miss (`/node`, `/dependencies`) or removed endpoint | no |
| `429` | rate limit — `Retry-After` present | no |
| `5xx` | server error | no |

> A zero-result `/search` is **not** a `404` — it returns `200` with an empty
> `nodes` array and settles normally; the targeted scan itself is the billable
> work. Only point lookups (`/node`, `/dependencies`) `404` on a miss.

Errors come back wrapped in the standard envelope:

```json
{ "data": null, "message": "…", "statusCode": 404 }
```

---

## 7. Minimal client (Node, ~10 lines)

```ts
import { x402Client }       from '@x402/core/client';
import { ExactEvmScheme }   from '@x402/evm/exact/client';
import { wrapFetchWithPayment } from '@x402/fetch';
import { privateKeyToAccount } from 'viem/accounts';

const signer = privateKeyToAccount(process.env.EVM_PRIVATE_KEY as `0x${string}`);
const client = new x402Client();
client.register('eip155:*', new ExactEvmScheme(signer));
const fetchPaid = wrapFetchWithPayment(fetch, client);

const res  = await fetchPaid('https://risk.yo.xyz/api/v1/agent/search?q=morpho');
const json = await res.json();                       // { data: { nodes }, … }
const receipt = res.headers.get('payment-response'); // base64 settlement receipt
```

Fund the signer wallet with a small balance of USDC on Base mainnet (no ETH
required — the facilitator pays gas). At the base price, `$1` covers ~1,000
cheap calls; sustained heavy use costs more under the escalation rule above.

---

## 8. Update cadence and data freshness

Risk grades recompute continuously as the underlying on-chain data, oracle
prices, and protocol configurations change. When citing a grade in a downstream
artifact (report, tool call), quote both the grade and the access date.

---

## 9. Out of scope

Risk Graph is an analytical explorer. It does not provide financial advice,
custodial services, or trade execution. It exposes letter grades only, and
provides no bulk, listing, or full-dataset access.