---
slug: graph-advocate
name: graph-advocate
version: "2.9.1"
displayName: Graph Advocate
summary: "把区块链数据问题路由到对的Graph Protocol服务,返实时数据(社区下载版)"
  live data from 15...
license: MIT-0
description: |-
  Route any blockchain data question to the right Graph Protocol service。Returns live data from 15。Use when 需要数据分析、报表生成、统计洞察、数据可视化时使用。不适用于实时流数据处理。适用于独立开发者、企业团队和自动化工作流场景。
tags:
- Integrations
tools:
  - - read
- exec
pricing_tier: "L4"
pricing_model: "monthly"
suggested_price: 99.9
---


# Graph Advocate

Ask any blockchain data question in plain English. Get back **live data** — not just a recommendation.

## Routing

Match the user's intent to the right service. Load only the reference you need.

| Intent | Service | Reference | Use for |
| --- | --- | --- | --- |
| **Token balances, holders, swaps, NFTs** | token-api | [token-api.md](/api/v1/skills/graph-advocate/file?path=references%2Ftoken-api.md&ownerHandle=paulieb14) | Wallet data across EVM, Solana, TON |
| **Polymarket markets, OHLCV, P&L, positions** | token-api | [token-api.md](/api/v1/skills/graph-advocate/file?path=references%2Ftoken-api.md&ownerHandle=paulieb14) | REST endpoints under `/v1/polymarket/*` — no npm install |
| **Find a subgraph for a protocol** | subgraph-registry | [subgraph-registry.md](/api/v1/skills/graph-advocate/file?path=references%2Fsubgraph-registry.md&ownerHandle=paulieb14) | Search 15,500+ subgraphs by protocol/chain |
| **Aave lending data** | graph-aave-mcp | [aave.md](/api/v1/skills/graph-advocate/file?path=references%2Faave.md&ownerHandle=paulieb14) | 40 tools — V2/V3/V4, liquidations, rates |
| **Polymarket advanced (orderbook, disputes, trader winrate/drawdown)** | graph-polymarket-mcp | [polymarket.md](/api/v1/skills/graph-advocate/file?path=references%2Fpolymarket.md&ownerHandle=paulieb14) | 31 tools — live CLOB, UMA resolution, subgraph-specific P&L stats |
| **Hyperliquid perps — trader skill, vaults, liquidations** | token-api + `/hyperliquid/*` | [hyperliquid.md](/api/v1/skills/graph-advocate/file?path=references%2Fhyperliquid.md&ownerHandle=paulieb14) | Raw markets/users/vaults via token-api; derived skill scores via GA's paid `/hyperliquid/*` endpoints |
| **Cross-protocol lending** | graph-lending-mcp | — | Messari standardized — 40+ protocols on 15 chains |
| **Limitless prediction markets** | graph-limitless-mcp | — | Markets on Base |
| **Cross-venue prediction-market spread (Polymarket ↔ Limitless)** | `/predmarket/spread` (paid) | — | Same-topic markets paired across venues, per-pair yes-mid spread (bps), arbitrage direction. JOIN single-venue passthroughs can't return. $0.05 USDC. |
| **Cross-source prediction-market spread (Kalshi ↔ Polymarket)** | `/kalshi-polymarket/spread` (paid) | — | Same-topic markets across Kalshi + Polymarket with mid-spread and arbitrage direction. $0.05 USDC. |
| **Agent reputation score (0-100)** | `/agent/score` (paid) | — | Composite from ERC-8004 registration + USDC settlement velocity + on-chain feedback registry, aggregated across all of owner's agents. Hard 8004 gate filters burns/CEX. Buyer-agent's "should I trust this peer" call. Response includes counterparty-ref-v1 conformant SHA-256 + preimage + canonical JCS string so a verifier can re-derive byte-exact without callback. $0.02 USDC. |
| **Kalshi consensus trend** | `/kalshi/consensus-trend` (paid) | — | Slope/acceleration/volatility band from Kalshi forecast_history. $0.05 USDC. |
| **Kalshi sports live-edge** | `/kalshi/sports-live-edge` (paid) | — | Play-by-play momentum vs market candlesticks; flags latency-arb windows. $0.05 USDC. |
| **Predict.fun prediction markets** | predictfun-mcp | — | BNB Chain prediction markets |
| **x402 payment analytics — NL question** | `/ask` (paid) | — | Natural-language Q&A over 132M settlements + daily_stats (May 2025 → Jun 2026). Sonnet + DuckDB. $0.05 USDC. |
| **x402 address lookup — onchain receipts** | `/onchain-x402/address` (paid) | — | Decentralized lookup via x402 Base subgraph: lifetime stats by role (payer/recipient), recent payments, facilitator, indexed_through_block. $0.01 USDC. |
| **x402 payment analytics (legacy reference)** | x402-analytics | [x402.md](/api/v1/skills/graph-advocate/file?path=references%2Fx402.md&ownerHandle=paulieb14) | Payment volume, facilitators, daily stats on Base |
| **Raw block data, streaming** | substreams | — | Traces, logs, custom transformations |
| **Agent discovery (ERC-8004)** | 8004scan | — | Find AI agents by capability |
| **MCP server auth** | mcp8004 | — | ERC-8004 identity verification |

**Polymarket routing rule:** Prefer `token-api` for common queries (markets, OHLCV, activity, user positions, P&L, platform stats). Only route to `graph-polymarket-mcp` for advanced queries: live orderbook depth, live spreads, disputed markets, UMA resolution, trader winrate/drawdown/profit factor, CTF splits/merges/redemptions.

If the request spans two services, use both and combine results.

## 示例

```text
"Top 10 USDC holders on Ethereum"           → token-api
"Best subgraph for Uniswap V3 on Arbitrum?" → subgraph-registry
"Aave V3 liquidations above $50K"           → graph-aave-mcp
"Hottest Polymarket markets"                → token-api (/v1/polymarket/markets)
"Polymarket OHLCV for Bitcoin market"       → token-api (/v1/polymarket/markets/ohlc)
"Polymarket trader P&L for 0x..."           → token-api (/v1/polymarket/users/positions)
"Polymarket live orderbook depth"           → graph-polymarket-mcp (advanced)
"Polymarket trader winrate/drawdown"        → graph-polymarket-mcp (subgraph P&L stats)
"Score Hyperliquid trader 0x..."            → /hyperliquid/score (paid)
"Hyperliquid top traders for HYPE"          → /hyperliquid/screen (paid)
"Evaluate Hyperliquid vault 0x..."          → /hyperliquid/vault (paid)
"Compare Aave vs Compound TVL"              → graph-lending-mcp
"x402 payment volume on Base today"         → x402-analytics
"Top 10 x402 recipients in the last 30 days" → /ask (paid, NL→SQL)
"When did x402 volume on Base inflect?"     → /ask (paid, NL→SQL)
"Has 0x0FF5A6… ever been paid via x402?"     → /onchain-x402/address (paid, decentralized)
"Polymarket vs Limitless spread on 'trump'"  → /predmarket/spread (paid, cross-venue JOIN)
"Kalshi vs Polymarket fed-rate arbitrage"    → /kalshi-polymarket/spread (paid)
"Find agents that do trading"               → 8004scan
```

## How It Works

1. Agent sends plain-English question
2. Graph Advocate identifies the best service
3. Searches the subgraph registry (15,500+ subgraphs with query hints)
4. Executes the query and returns **live data** in the response
5. Includes `get_started` link for agents to get their own free API key

## Response Format

```json
{
  "recommendation": "subgraph-registry",
  "reason": "why this service fits",
  "confidence": "high",
  "query_ready": { "tool": "...", "args": {...} },
  "execution_result": { "source": "subgraph-gateway", "data": {...} },
  "get_started": "Free API key: https://thegraph.com/studio/",
  "cache_for_seconds": 86400
}
```

## Endpoints

| Method | URL | Purpose |
| --- | --- | --- |
| POST | `https://graphadvocate.com/` | A2A JSON-RPC 2.0 |
| POST | `https://graphadvocate.com/chat` | Simple HTTP chat |
| GET | `https://graphadvocate.com/.well-known/agent-card.json` | Agent card |
| GET | `https://graphadvocate.com/agents/capabilities.json` | Machine-readable capability list |
| GET | `https://graphadvocate.com/mcp/catalog` | List of installable MCP servers |
| GET | `https://graphadvocate.com/llms.txt` | LLM-friendly discovery file |
| GET | `https://graphadvocate.com/quota?sender=0x...` | Free-tier quota remaining today (no charge) |
| GET | `https://graphadvocate.com/dashboard` | Live monitoring |
| POST | `https://graphadvocate.com/feedback` | Agent feedback |

## Default mode: no wallet, free tier

This skill is **fully functional with no wallet attached**. The default routing —
plain-English question in, JSON recommendation + live data out — runs against the
free tier and never asks for funds. Agents that don't expose an x402-enabled
runtime simply never see a payment challenge.

If you're evaluating Graph Advocate for the first time, start without a wallet,
use the free tier, and decide later whether the paid endpoints are worth opting
into.

## Optional paid mode (opt-in)

Some endpoints settle in USDC on Base via the x402 protocol. Paid mode is
**opt-in**: it only activates when your agent runtime is configured to accept
x402 payment challenges. Without that configuration, paid endpoints return
`402 Payment Required` and the call stops there — no funds move.

### Pricing

* `/route` — 3 free queries/sender/day, then **$0.01 USDC** per call (Base mainnet)
* `/polymarket/*` — paid from call 1 ($0.01 - $0.05 per call)
* `/hyperliquid/*` — paid from call 1 ($0.02 - $0.10 per call)
* `/predmarket/spread` — paid from call 1 (**$0.05 USDC**) — Polymarket ↔ Limitless cross-venue spread on a topic. POST `{topic, limit?}` returns per-pair yes-mid spread (bps) and arbitrage direction. JOIN that single-venue passthroughs structurally can't return.
* `/kalshi-polymarket/spread` — paid from call 1 (**$0.05 USDC**) — Kalshi ↔ Polymarket cross-source spread on a topic.
* `/kalshi/consensus-trend`, `/kalshi/sports-live-edge` — paid from call 1 (**$0.05 USDC** each).
* `/ask` — paid from call 1 (**$0.05 USDC**) — natural-language Q&A over the x402 Base settlements warehouse. 132M+ payments + pre-aggregated `daily_stats` (388 days). Returns `{answer, sql_trace, model, upstream_ms}` so callers can verify the data path.
* `/onchain-x402/address` — paid from call 1 (**$0.01 USDC**) — decentralized address lookup against the x402 Base subgraph on The Graph Network. POST `{address}` returns lifetime stats (payer + recipient roles), recent 10 payments in each direction, facilitator metadata, and `indexed_through_block` for freshness.

### 402 challenge — preview before paying

Every paid endpoint's 402 response body includes an `output_example` field with a sample of the payload you'll receive after paying. Inspect this before signing — if the shape doesn't fit your use case, bail without spending.

### Per-call approval (recommended)

Every paid call is preceded by an HTTP 402 challenge that names the price,
the recipient address, and the settlement network:

```text
HTTP/1.1 402 Payment Required
X-Payment: { "amount": "0.01", "currency": "USDC", "network": "base",
             "recipient": "0x0FF5A6ec…7C86", "challenge": "<nonce>" }
```

The 402 challenge is the per-call approval surface. **Configure your runtime
to surface 402 challenges to the user** before any payment is signed — most
x402 clients accept an interactive-approval flag (e.g. `confirmBeforePay`).
With per-call approval enabled, you see the exact price and recipient on every
paid request and decide yes/no per call. This is the recommended posture for
any wallet that holds more than a trivial amount.

If you instead configure your runtime to accept 402 challenges automatically,
paid calls settle without an interactive prompt. That is a runtime-level choice,
not a property of this skill — and if you choose it, the spend controls below
become load-bearing.

### Free-quota visibility (no-charge)

Before any paid call, check today's remaining free-tier quota:

```text
GET https://graphadvocate.com/quota?sender=0x<your-agent-address>
```

Returns:

```json
{
  "sender": "0x…",
  "free_quota_daily": 3,
  "used_today": 1,
  "remaining_today": 2,
  "free_tier_exhausted": false,
  "next_call_paid": false,
  "price_usdc_per_paid_call": 0.01
}
```

`/quota` is a no-charge metadata route. Use it to:

1. Display "N free queries remaining today" in your UI before the agent runs.
2. Halt autonomous loops when `remaining_today` hits 0 instead of accepting
   the 402 challenge.
3. Audit per-sender spend by polling daily.

### Required spend controls before autonomous use

1. **Dedicated low-balance wallet.** Fund only what you're willing to spend
   in a session (e.g. $5 USDC). Never connect a wallet that holds your treasury.
2. **Spend caps in your agent runtime.** Most x402 clients accept
   `maxAmountPerCall` and `maxTotalSpend` parameters. If yours does not, wrap
   calls to this skill in a counter that breaks after N invocations.
3. **Stop conditions.** Add at least one of:
   * Hard cap on call count per task (e.g. `max_calls_per_run = 5`)
   * Time bound on the task (e.g. abort after 5 minutes)
   * Cost ceiling check before each call (read wallet USDC balance; halt if below threshold)
4. **First-run probe mode.** Treat the first execution as a probe — log every
   call, inspect spend, then enable autonomous mode only after confirming the
   per-task cost matches expectations.

### Receipts and no-charge surface

* Every paid call returns an `x-payment-response` header with the on-chain
  settlement reference. Log it. If a call doesn't return that header but charged
  your wallet, file an issue — the contract is "no settlement, no charge."
* **No-charge endpoints** never trigger payment: `/.well-known/agent-card.json`,
  `/agents/capabilities.json`, `/mcp/catalog`, `/llms.txt`, `/dashboard`,
  `/chat`, `/quota`, `GET /`.

Payments are received by Ampersend smart account `0x0FF5A6ecef783BBA35463ec2F8403B9B5e9e7C86`.

## External Endpoints

| Endpoint | Data sent | Purpose |
| --- | --- | --- |
| `graphadvocate.com` | Your plain-English query | Routes to the right Graph service |
| `gateway.thegraph.com/api/` | GraphQL queries | Executes subgraph queries for live data |
| `api.pinax.network/` | REST requests | Fetches token/NFT/swap data |
| `api.studio.thegraph.com` | GraphQL queries | x402 payment analytics |

## Security & Privacy

* **Instruction-only skill** — no code is downloaded or executed on your machine
* **No credentials required** — Graph Advocate does not need API keys from you
* **No local file access** — reads nothing from your filesystem
* **Stateless** — no session data persists between requests

## Identity

* **ERC-8004:** Agent #734 (Arbitrum), #41,034 (Base)
* **ENS:** graphadvocate.eth
* **Ampersend:** [app.ampersend.ai/discover/agent/8453:41034](https://app.ampersend.ai/discover/agent/8453:41034)

## Trust Statement

By using this skill, your plain-English data queries are sent to `graphadvocate.com` (hosted on Railway, operated by @paulieb14). The service returns structured JSON with live data. Queries may include wallet addresses and protocol/trading intent — do not send sensitive private context (private keys, seed phrases, internal strategy details) and only install if you trust this endpoint operator.

**Paid mode is opt-in.** This skill never requests credentials from you. Paid
endpoints only settle when your agent runtime is configured to accept x402
payment challenges. Configure interactive approval if you want a per-call
y/N prompt, and always use a low-balance wallet — see the "Optional paid mode"
section above for the recommended posture and spend controls.

## Links

* GitHub: <https://github.com/PaulieB14/graph-advocate>
* The Graph: <https://thegraph.com>
* Subgraph Studio: <https://thegraph.com/studio>

## 依赖说明

### 运行环境
- **Agent平台**: 支持SKILL.md的任意AI Agent(Claude Code / Cursor / Codex / Gemini CLI等)
- **操作系统**: Windows / macOS / Linux

### 依赖说明
| 依赖项 | 类型 | 是否必需 | 获取方式 |
|:-------|:-----|:---------|:---------|
| LLM API | API | 必需 | 由Agent内置LLM提供 |

### API Key 配置
- 本Skill基于Markdown指令,无需额外API Key(除内容中明确标注的外部API)

### 可用性分类
- **分类**: MD+EXEC(纯Markdown指令,部分功能需要exec命令行执行能力)
- **说明**: 基于Markdown的AI Skill,通过自然语言指令驱动Agent执行任务

## 核心能力

- Route any blockchain data question to the right Graph Protocol service
- Returns live data from 15
- 触发关键词: graph, route, advocate, right, data, question, blockchain

## 适用场景

| 场景 | 输入 | 输出 |
|------|------|------|
| 基础使用 | 用户请求 | 处理结果 |

**不适用于**：需要人工判断的复杂决策场景

## 使用流程

1. 确认运行环境满足依赖说明中的要求
2. 根据适用场景选择合适的使用方式
3. 执行操作并检查输出结果
4. 如遇错误，参考错误处理章节

## 错误处理

| 错误场景 | 原因 | 处理方式 |
|---------|------|---------|
| 配置错误 | 参数缺失或格式错误 | 检查依赖说明中的配置要求 |
| 运行时错误 | 运行环境不满足 | 确认运行环境符合依赖说明 |
| 网络错误 | 连接超时或不可达 | 检查网络连接后重试，参考国内替代方案 |

## 常见问题

### Q1: 如何开始使用Graph Advocate？
A: 请先阅读使用流程章节，确认环境满足依赖说明中的要求。

### Q2: 遇到错误怎么办？
A: 请参考错误处理章节，按照表格中的处理方式操作。

### Q3: Graph Advocate有什么限制？
A: 请参考已知限制章节了解具体限制。

## 已知限制

- 需要API Key，无Key环境无法使用