> For the complete documentation index, see [llms.txt](https://docs.yo.xyz/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.yo.xyz/yo-risk-graph/agent-api.md).

# Agent API

For full risk grading and dependency mapping across pools, assets, protocols, and chains. Built for AI agents and programmatic clients. No API key required, plain pay-per-query via the x402 protocol.

**Base URL**

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

All endpoints resolve under `https://risk.yo.xyz/api/v1/agent/...`. Treat `resource.url` in the 402 invoice as the canonical source rather than hardcoding this host — if it ever moves, agents reading from the invoice keep working without a code change.

#### Payment

Every `/api/v1/agent/*` route is monetized via [x402](https://x402.org) (v2).

|                |                                                                                      |
| -------------- | ------------------------------------------------------------------------------------ |
| Network        | `eip155:8453` (Base mainnet)                                                         |
| Asset          | USDC — `0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913` (6 decimals)                     |
| Settlement     | EIP-3009 `transferWithAuthorization` via Coinbase CDP — payer pays no gas, only USDC |
| Onboarding fee | None — plain pay-per-query from the first call                                       |
| Rate limit     | \~10 requests/second per payer                                                       |

**Flow**

1. Send an unpaid request → receive `402 Payment Required` with a base64-encoded invoice in the `PAYMENT-REQUIRED` header, including a canonical `resource.url`.
2. Sign the invoice amount (use [`@x402/fetch`](https://www.npmjs.com/package/@x402/fetch) or [`@x402/core`](https://www.npmjs.com/package/@x402/core) to handle this automatically).
3. Retry with an `X-PAYMENT` header.
4. Receive the resource with a `PAYMENT-RESPONSE` header confirming on-chain settlement (verifiable on [Basescan](https://basescan.org)). Only successful (`2xx`) responses are charged. `400`, `403`, `404`, `429`, and `5xx` responses are free — point lookups (`/node`, `/dependencies`) are safe to probe. `/search` is the one exception: it always settles, even on a zero-result query, since the scan itself is the billable work.

If your price changes between calls (see escalation below), the server re-issues a fresh `402` with the corrected amount — always sign the amount in the invoice you actually receive, not a cached one.

**Minimal client**

```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 USDC balance on Base. No ETH needed — the facilitator pays gas. At base pricing, **$1 covers roughly 1,000 cheap calls** (schema/search); heavier use costs more under the escalation rule below.

#### Endpoints

| Endpoint                                 | Price  | Returns                                                                                                                      |
| ---------------------------------------- | ------ | ---------------------------------------------------------------------------------------------------------------------------- |
| `GET /api/v1/agent/schema`               | $0.001 | Data model: node types, edge types, grade letters. Call this first.                                                          |
| `GET /api/v1/agent/search?q=`            | $0.001 | Lean teaser per hit — `name`, `network`, `tvlUsd`/`marketCapUsd`, `address`/`uniqueKey`. **No grade.** Capped at 10 results. |
| `GET /api/v1/agent/node/:nodeId`         | $0.05  | Full properties + grade `_riskTier` + `riskBreakdown` (rationale as Q\&A pairs). `404` (free) if not indexed.                |
| `GET /api/v1/agent/dependencies?nodeId=` | $1.00  | A pool's direct (1-hop) dependencies — edges and neighboring nodes, each stamped with `lastUpdatedAt`.                       |

`/search` and `/node` are deliberately not interchangeable: `/search` is for finding an entity cheaply, `/node` is for reading its grade. Always follow up a search hit with a `/node` call to get the actual grade.

**The risk signal**

The only risk value exposed is `_riskTier` — a letter grade from **A** (safest) to **F** (riskiest), present on `/node` and `/dependencies` results (not on `/search` teasers). `/node` also returns **`riskBreakdown`**: the grade's rationale as plain `{ question, answer }` pairs.

**Search filters**

| Param   | Description                                                   |
| ------- | ------------------------------------------------------------- |
| `q`     | Required. Asset address or protocol/asset name. No wildcards. |
| `label` | Restrict to `Pool`, `Asset`, `Protocol`, or `Chain`           |
| `limit` | 1–10, default 10                                              |
| `tvl`   | Comparator, e.g. `>1000000`                                   |
| `grade` | Comparator over A–F, e.g. `<=B`                               |

**Suggested flow**

```
1. GET /schema                          → learn the node/edge model
2. GET /search?q=<name-or-address>      → find the entity (teaser only)
3. GET /node/<nodeId>                   → read its grade + rationale
4. GET /dependencies?nodeId=<poolId>    → map its dependencies (with freshness stamps)
```

#### Full reference

Machine-readable agent documentation:

* [llms.txt](https://www.yo.xyz/risk-graph/llms.txt) — endpoint catalogue and quick reference
* [llms-full.txt](https://www.yo.xyz/risk-graph/llms-full.txt) — full DTO schemas, error semantics, worked examples


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.yo.xyz/yo-risk-graph/agent-api.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.