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 (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 or @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). 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

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 — endpoint catalogue and quick reference

• llms-full.txt — full DTO schemas, error semantics, worked examples