BlockRunAI · VickyXAI · Aug 4, 2026 · Aug 4, 2026
diff --git a/docs/SUMMARY.md b/docs/SUMMARY.md
@@ -66,6 +66,8 @@
 * [Polymarket Funding](api-reference/polymarket-funding.md)
 * [Modal Sandbox](api-reference/modal-sandbox.md)
 * [Surf — Crypto Data](api-reference/surf.md)
+* [DefiLlama](api-reference/defillama.md)
+* [Market Data (Pyth)](api-reference/market-data.md)
 * [Multi-chain RPC](api-reference/multi-chain-rpc.md)
 * [Phone & Voice](api-reference/voice-phone.md)
 * [Models](api-reference/models.md)

diff --git a/docs/api-reference/defillama.md b/docs/api-reference/defillama.md
@@ -0,0 +1,142 @@
+---
+title: DefiLlama
+description: DeFi protocol TVL, per-chain TVL, yield pools and token prices from DefiLlama's dataset, paid per call in USDC over x402 — no account, no API key.
+---
+
+# DefiLlama
+
+DeFi's reference dataset — every protocol DefiLlama tracks, TVL by chain, every
+yield pool, and token prices across chains. Pay per call in USDC over x402; no
+account and no API key.
+
+DefiLlama publishes under Apache 2.0 with explicit free-for-commercial-use
+terms. BlockRun wraps it with metering, timeouts and a single payment rail so an
+agent can budget a call the same way it budgets any other endpoint.
+
+## Endpoints
+
+| Endpoint | Method | Price | Description |
+|----------|--------|-------|-------------|
+| `/api/v1/defillama/protocols` | GET | $0.006 | Every DeFi protocol tracked, with current and historical TVL across chains |
+| `/api/v1/defillama/protocol/{slug}` | GET | $0.006 | Detailed TVL + breakdown for one protocol |
+| `/api/v1/defillama/chains` | GET | $0.006 | TVL for every chain DefiLlama tracks |
+| `/api/v1/defillama/yields` | GET | $0.006 | Every tracked yield pool (lending, LPs, staking, vaults) with current APY/TVL |
+| `/api/v1/defillama/prices/{coins}` | GET | $0.002 | Token price lookup, comma-separated coin identifiers |
+
+Prices are quoted in every 402 response. Read them at request time rather than
+copying from this page.
+
+---
+
+## GET /api/v1/defillama/protocols
+
+Every protocol DefiLlama indexes, with current TVL and per-chain breakdown.
+
+```bash
+curl https://blockrun.ai/api/v1/defillama/protocols \
+  -H "X-Payment: <x402_payment_token>"
+```
+
+Returns a JSON array. Each entry carries `name`, `slug`, `category`, `chains`,
+`tvl` and change-over-time fields. It is a large payload — expect several MB.
+
+---
+
+## GET /api/v1/defillama/protocol/{slug}
+
+One protocol in detail, addressed by its DefiLlama slug.
+
+```bash
+curl https://blockrun.ai/api/v1/defillama/protocol/aave \
+  -H "X-Payment: <x402_payment_token>"
+```
+
+| Parameter | In | Required | Description |
+|-----------|----|----------|-------------|
+| `slug` | path | Yes | DefiLlama protocol slug — `aave`, `uniswap`, `lido`, … |
+
+Slugs come from the `slug` field of `/protocols`. An unknown slug returns `404`
+and is **not** charged.
+
+The heaviest protocols (`uniswap`, for one) return multi-MB payloads; the
+upstream timeout is 25s.
+
+---
+
+## GET /api/v1/defillama/chains
+
+Current TVL totals for every chain.
+
+```bash
+curl https://blockrun.ai/api/v1/defillama/chains \
+  -H "X-Payment: <x402_payment_token>"
+```
+
+---
+
+## GET /api/v1/defillama/yields
+
+Every yield pool DefiLlama tracks, with APY and TVL — lending markets, LP
+positions, staking and vaults.
+
+```bash
+curl https://blockrun.ai/api/v1/defillama/yields \
+  -H "X-Payment: <x402_payment_token>"
+```
+
+Filter client-side on `chain`, `project`, `symbol`, `apy` and `tvlUsd`.
+
+---
+
+## GET /api/v1/defillama/prices/{coins}
+
+Token prices in DefiLlama's coin syntax. Cheaper than the other four at $0.002
+because it is a point lookup rather than a full dataset.
+
+```bash
+curl "https://blockrun.ai/api/v1/defillama/prices/coingecko:bitcoin,ethereum:0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2" \
+  -H "X-Payment: <x402_payment_token>"
+```
+
+| Parameter | In | Required | Description |
+|-----------|----|----------|-------------|
+| `coins` | path | Yes | Comma-separated coin identifiers |
+
+Identifier forms:
+
+- `coingecko:<id>` — e.g. `coingecko:bitcoin`
+- `<chain>:<address>` — e.g. `ethereum:0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2`, `solana:So11111111111111111111111111111111111111112`
+
+The response is an object keyed by the identifier you passed, each with
+`price`, `symbol`, `decimals` and `timestamp`.
+
+---
+
+## Errors
+
+| Status | Meaning | Charged? |
+|--------|---------|----------|
+| `402` | Payment required — the response carries the exact amount and `payTo` | No |
+| `404` | Unknown protocol slug or coin identifier | No |
+| `502` | DefiLlama upstream error or timeout | No |
+
+Payment settles only after a successful upstream response, so a failed call
+never costs you anything.
+
+## What's next?
+
+::::cards
+
+:::card{title="Surf — Crypto Data" href="surf.md" icon="ChartLine"}
+Exchange, on-chain and social data across 83 endpoints.
+:::
+
+:::card{title="0x Swap (DEX)" href="zerox-swap.md" icon="ArrowLeftRight"}
+Swap quotes and gasless trading — free to call.
+:::
+
+:::card{title="How x402 Works" href="../x402/how-it-works.md" icon="Zap"}
+The 402 response and on-chain settlement, end to end.
+:::
+
+::::
diff --git a/docs/api-reference/exa-search.md b/docs/api-reference/exa-search.md
@@ -13,19 +13,19 @@ LLMs have a knowledge cutoff. When an agent needs to answer "what happened last
 
 Exa gives agents a live internet connection with structured, grounded results — not HTML soup, but clean text ready to feed into your next LLM call.
 
-**A complete research workflow costs $0.036:**
-- 1 search ($0.012) → find relevant URLs
-- 5 page reads ($0.012) → get full content
-- 1 synthesized answer ($0.012) → grounded conclusion
+**A complete research workflow costs $0.033:**
+- 1 search ($0.011) → find relevant URLs
+- 5 page reads in one call ($0.003/URL → $0.011) → get full content
+- 1 synthesized answer ($0.011) → grounded conclusion
 
 ## Endpoints
 
 | Endpoint | Method | Price | Description |
 |----------|--------|-------|-------------|
-| `/api/v1/exa/search` | POST | $0.012 | Neural web search — find relevant URLs for a query |
-| `/api/v1/exa/answer` | POST | $0.012 | Get a cited, synthesized answer to any question |
-| `/api/v1/exa/contents` | POST | $0.002/URL | Fetch full Markdown text from a list of URLs |
-| `/api/v1/exa/find-similar` | POST | $0.012 | Find pages similar to a given URL |
+| `/api/v1/exa/search` | POST | $0.011 | Neural web search — find relevant URLs for a query |
+| `/api/v1/exa/answer` | POST | $0.011 | Get a cited, synthesized answer to any question |
+| `/api/v1/exa/contents` | POST | $0.003/URL | Fetch full Markdown text from a list of URLs |
+| `/api/v1/exa/find-similar` | POST | $0.011 | Find pages similar to a given URL |
 
 ---
 
@@ -194,7 +194,7 @@ const analysis = await client.chat("anthropic/claude-opus-5", [
 
 ### 2. Fact-Checking Agent — No Hallucinations
 
-Agent needs a reliable answer to a factual question. Cost: $0.012.
+Agent needs a reliable answer to a factual question. Cost: $0.011.
 
 ```typescript
 const result = await client.exaAnswer(
@@ -207,7 +207,7 @@ console.log("Sources:", result.citations.map(c => c.url));
 
 ### 3. Competitive Intelligence — Find Similar Projects
 
-Discover what's being built in your space. Cost: $0.012.
+Discover what's being built in your space. Cost: $0.011.
 
 ```typescript
 const similar = await client.exaFindSimilar("https://blockrun.ai", {
@@ -235,7 +235,7 @@ const readmes = await client.exaContents([repos.results[0].url]);
 
 ### 5. Monitoring Agent — Track News About a Topic
 
-Weekly check on what's happening. Cost: $0.012/run.
+Weekly check on what's happening. Cost: $0.011/run.
 
 ```typescript
 const lastWeek = new Date();
@@ -317,9 +317,9 @@ const similar = await client.exaFindSimilar("https://blockrun.ai", { numResults:
 
 | Endpoint | Price per call |
 |----------|---------------|
-| `/exa/search` | $0.012 |
-| `/exa/answer` | $0.012 |
-| `/exa/find-similar` | $0.012 |
+| `/exa/search` | $0.011 |
+| `/exa/answer` | $0.011 |
+| `/exa/find-similar` | $0.011 |
 | `/exa/contents` | $0.002 per URL |
 
 Payment is in USDC on Base or Solana via x402. No account needed — your wallet is your identity.

diff --git a/docs/api-reference/market-data.md b/docs/api-reference/market-data.md
@@ -0,0 +1,127 @@
+---
+title: Market Data (Pyth)
+description: Spot prices and OHLC history for stocks, crypto, FX and commodities from Pyth Network — crypto, FX and commodities are free; equities are $0.0010 per call.
+---
+
+# Market Data (Pyth)
+
+Spot prices and historical OHLC bars across four asset classes, grounded in
+[Pyth Network](https://pyth.network) on-chain feeds.
+
+**Crypto, FX and commodity prices are free.** Equities — US and international —
+are `$0.0010` per call, because those feeds are broker-fed rather than
+open on-chain data. Every `/list` endpoint is free regardless of asset class.
+
+## Endpoints
+
+| Endpoint | Method | Price | Description |
+|----------|--------|-------|-------------|
+| `/api/v1/crypto/list` | GET | Free | Available crypto symbols |
+| `/api/v1/crypto/price/{symbol}` | GET | Free | Crypto spot price |
+| `/api/v1/crypto/history/{symbol}` | GET | Free | Crypto OHLC bars |
+| `/api/v1/fx/list` | GET | Free | Available FX pairs |
+| `/api/v1/fx/price/{symbol}` | GET | Free | FX spot rate |
+| `/api/v1/fx/history/{symbol}` | GET | Free | FX OHLC bars |
+| `/api/v1/commodity/list` | GET | Free | Available commodities |
+| `/api/v1/commodity/price/{symbol}` | GET | Free | Commodity spot price |
+| `/api/v1/commodity/history/{symbol}` | GET | Free | Commodity OHLC bars |
+| `/api/v1/usstock/list` | GET | Free | US tickers |
+| `/api/v1/usstock/price/{symbol}` | GET | $0.0010 | US equity spot price |
+| `/api/v1/usstock/history/{symbol}` | GET | $0.0010 | US equity OHLC bars |
+| `/api/v1/stocks/{market}/list` | GET | Free | Tickers for one non-US market |
+| `/api/v1/stocks/{market}/price/{symbol}` | GET | $0.0010 | Non-US equity spot price |
+| `/api/v1/stocks/{market}/history/{symbol}` | GET | $0.0010 | Non-US equity OHLC bars |
+
+`GET` and `POST` both work on every path; `POST` exists so callers that cannot
+attach headers to a `GET` still have a route.
+
+## Symbol formats
+
+Always resolve symbols from the matching `/list` endpoint rather than guessing.
+
+| Asset class | Format | Examples |
+|-------------|--------|----------|
+| Crypto | `BASE-QUOTE` | `BTC-USD`, `ETH-USD`, `SOL-USD` |
+| FX | `BASE-QUOTE` | `EUR-USD`, `GBP-USD`, `JPY-USD` |
+| Commodity | `METAL-USD` / ticker | `XAU-USD` (gold), `XAG-USD` (silver) |
+| US equity | Plain ticker | `AAPL`, `TSLA`, `NVDA`, `SPY` |
+| Non-US equity | Per-market convention | HKEX `-HK` suffix, TSE 4-digit, KRX 6-digit, LSE/XETRA/Euronext alpha |
+
+`/list` takes `q` (substring filter) and `limit` (max 2000, default 100).
+
+## Markets
+
+`{market}` for the `/stocks/` family: `us`, `hk`, `jp`, `kr`, `gb`, `de`, `fr`,
+`nl`, `ie`, `lu`, `cn`, `ca`. `/api/v1/usstock/*` is a legacy alias for
+`/api/v1/stocks/us/*` and behaves identically.
+
+---
+
+## Spot price
+
+```bash
+# Free — no payment header needed
+curl https://blockrun.ai/api/v1/crypto/price/BTC-USD
+
+# Paid — $0.0010
+curl https://blockrun.ai/api/v1/usstock/price/AAPL \
+  -H "X-Payment: <x402_payment_token>"
+```
+
+| Parameter | In | Required | Description |
+|-----------|----|----------|-------------|
+| `symbol` | path | Yes | Any symbol from the matching `/list` |
+| `session` | query | No | Trading session hint — `regular` or `extended` |
+
+The response carries `symbol`, `price`, `confidence` (Pyth's interval around
+the price), `publishTime` and `source`. Treat `confidence` as real: a wide
+interval means the feed is uncertain, not that the price is precise.
+
+---
+
+## OHLC history
+
+```bash
+curl "https://blockrun.ai/api/v1/crypto/history/BTC-USD?resolution=D&from=1735689600&to=1738368000"
+```
+
+| Parameter | In | Required | Description |
+|-----------|----|----------|-------------|
+| `symbol` | path | Yes | Any symbol from the matching `/list` |
+| `resolution` | query | No | Bar size — `1`, `5`, `15`, `60`, `240`, `D`, `W`, `M`. Default `D` |
+| `from` | query | No | Start, unix seconds |
+| `to` | query | No | End, unix seconds. Defaults to now |
+| `session` | query | No | `regular` or `extended` |
+
+---
+
+## Discovery
+
+Free endpoints still answer a `402` when you ask for one without payment — that
+response is x402 discovery metadata for indexers, not a charge. A plain `GET`
+returns `200` and the data.
+
+## Errors
+
+| Status | Meaning | Charged? |
+|--------|---------|----------|
+| `402` | Payment required (paid feeds), or discovery metadata (free feeds) | No |
+| `404` | Symbol not found — check the matching `/list` | No |
+
+## What's next?
+
+::::cards
+
+:::card{title="Surf — Crypto Data" href="surf.md" icon="ChartLine"}
+Exchange depth, liquidations, on-chain SQL and wallet labels.
+:::
+
+:::card{title="DefiLlama" href="defillama.md" icon="Landmark"}
+Protocol TVL, per-chain TVL and yield pools.
+:::
+
+:::card{title="Multi-chain RPC" href="multi-chain-rpc.md" icon="Link"}
+JSON-RPC to 40 chains through one endpoint.
+:::
+
+::::