Skill: paulieb14/graph-advocate (version 2.5.0)

--- name: graph-advocate description: "Route any blockchain data question to the right Graph Protocol service. Returns live data from 15,500+ subgraphs, Token API (EVM/Solana/TON + Polymarket + Hyperliquid), x402 payment analytics, and protocol-specific MCP packages. Trigger keywords: subgraph, token, balance, holder, swap, pool, TVL, DeFi, NFT, Aave, Uniswap, Polymarket, Hyperliquid, perps, ENS, governance, x402, prediction market, onchain data, blockchain." version: 2.5.0 homepage: https://github.com/PaulieB14/graph-advocate metadata: clawdbot: emoji: "⛓️" --- # 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](references/token-api.md) | Wallet data across EVM, Solana, TON | | **Polymarket markets, OHLCV, P&L, positions** | token-api | [token-api.md](references/token-api.md) | REST endpoints under `/v1/polymarket/*` — no npm install | | **Find a subgraph for a protocol** | subgraph-registry | [subgraph-registry.md](references/subgraph-registry.md) | Search 15,500+ subgraphs by protocol/chain | | **Aave lending data** | graph-aave-mcp | [aave.md](references/aave.md) | 40 tools — V2/V3/V4, liquidations, rates | | **Polymarket advanced (orderbook, disputes, trader winrate/drawdown)** | graph-polymarket-mcp | [polymarket.md](references/polymarket.md) | 31 tools — live CLOB, UMA resolution, subgraph-specific P&L stats | | **Hyperliquid perps — trader skill, vaults, liquidations** | token-api + `/hyperliquid/*` | [hyperliquid.md](references/hyperliquid.md) | 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 | | **Predict.fun prediction markets** | predictfun-mcp | — | BNB Chain prediction markets | | **x402 payment analytics** | x402-analytics | [x402.md](references/x402.md) | 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. ## Quick Examples ``` "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 "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) ### 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: ``` 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: ``` 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 [REDACTED_SECRET]. ## 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 | | `token-api.thegraph.com/` | 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


Security scan verdicts — ClawScan: clean | static analysis: clean | VirusTotal: clean | SkillSpector: clean (LOW)