{ "markdown": "# Subgraph Registry\n\n\n \n\n\nAgent-friendly semantic classification of all subgraphs on [The Graph Network](https://thegraph.com).\n\nPre-computed index of **15,330 subgraphs** with domain classification, protocol type detection, schema fingerprinting, canonical entity mapping, and composite reliability scoring.\n\n> **What's new in 0.8.0** — three agent-discovery upgrades:\n> - **[Semantic search](#semantic-search)** via 384-dim embeddings (`semantic_search_subgraphs`)\n> - **[Schema evolution tracking](#schema-evolution)** with stability days surfaced on every result (`get_schema_changes`)\n> - **[OpenAPI 3.1 spec](#openapi)** auto-generated for MCP tools + REST routes, served at `/.well-known/openapi.json`\n\n## The Problem\n\nAgents querying The Graph need to discover and select the right subgraph before they can query data. Today this requires 3-4 tool calls (search, check volumes, fetch schema, infer structure) before any real work happens. This registry flips that: agents start with structured knowledge, not a blank slate.\n\n## What It Does\n\n1. **Crawls** all active subgraphs from the Graph Network meta-subgraph\n2. **Fetches** the GraphQL schema for every deployment\n3. **Extracts contract addresses** from each manifest's `dataSources` and `templates` — agents can answer \"which subgraph indexes contract 0x… on chain X?\"\n4. **Generates a per-subgraph starter GraphQL query** from the parsed schema (real top entity, real fields, sensible orderBy) — no more generic boilerplate that doesn't compile against most subgraphs\n5. **Classifies** each subgraph by domain, protocol type, canonical entities, and schema family\n6. **Scores** reliability using on-chain signals (query fees, volume, curation, stake)\n7. **Returns x402 + legacy query URLs** — agents can pay $0.01 USDC on Base per query (no API key) or use a Studio key\n8. **Publishes** as SQLite database + REST API + MCP server + **per-subgraph JSON-LD at `/.well-known/subgraph/{id}.jsonld`** for ecosystem crawlers\n9. **Generates** visual dashboards and bot-readable category files (auto-updated with each sync)\n\n---\n\n## Querying with x402 (no API key)\n\nEvery result includes `query_url_x402` alongside the legacy `query_url`. The Graph's public x402 gateway (live since 2026-05-08) accepts **$0.01 USDC on Base** per query with zero signup.\n\n```js\n// An x402-native agent — discovery to data in two calls\nconst { recommendations } = await mcp.call(\"recommend_subgraph\", {\n goal: \"find DEX trades on Arbitrum\",\n});\nconst top = recommendations[0];\n\n// POST your GraphQL query. The first call returns HTTP 402 with a\n// base64 `payment-required` header; the x402 client signs the\n// EIP-3009 USDC transfer on Base and retries automatically.\nconst data = await x402Fetch(top.query_url_x402, {\n method: \"POST\",\n body: JSON.stringify({ query: \"{ swaps(first: 5) { id amountUSD } }\" }),\n});\n```\n\nPricing manifest returned per subgraph:\n\n```json\n{\n \"amount_usd\": 0.01,\n \"asset\": \"USDC\",\n \"asset_contract\": \"0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913\",\n \"chain\": \"base\",\n \"network\": \"eip155:8453\",\n \"pay_to\": \"0x79DC34E41B2b591078d3dE222C43EcaaBD52FcCB\",\n \"scheme\": \"exact\",\n \"asset_transfer_method\": \"eip3009\"\n}\n```\n\nClient libraries: [`@graphprotocol/client-x402`](https://www.npmjs.com/package/@graphprotocol/client-x402), `x402-fetch`, or any generic x402 wrapper.\n\n---\n\n## Registry at a Glance\n\n

\n \"Subgraphs\n

\n\n

\n \"Subgraphs\n

\n\n

\n \"Subgraphs\n

\n\n

\n \"Reliability\n

\n\n> Charts auto-generated from `registry.db` on each sync. See [`python/generate_docs.py`](python/generate_docs.py).\n\n---\n\n## Browse by Category\n\n### Domains\n\nExplore subgraphs by use case — each file lists the top 25 subgraphs ranked by reliability score.\n\n| Domain | Count | File |\n|--------|-------|------|\n| [DeFi](docs/domains/defi.md) | 7,844 | Swaps, pools, lending, vaults, yield |\n| [NFTs](docs/domains/nfts.md) | 1,565 | Collections, marketplaces, sales |\n| Unclassified | 1,333 | Not confidently classified |\n| [Infrastructure](docs/domains/infrastructure.md) | 1,251 | Indexers, oracles, registries |\n| [Identity](docs/domains/identity.md) | 1,061 | ENS, name services, resolvers |\n| [Analytics](docs/domains/analytics.md) | 766 | Snapshots, metrics, historical data |\n| [DAO](docs/domains/dao.md) | 758 | Governance, proposals, voting |\n| [Gaming](docs/domains/gaming.md) | 585 | Players, quests, items, worlds |\n| [Social](docs/domains/social.md) | 167 | Profiles, posts, follows |\n\nFull index: [`docs/DOMAINS.md`](docs/DOMAINS.md)\n\n### Networks\n\nExplore subgraphs by blockchain — each file lists the top 25 subgraphs on that chain.\n\n| Network | Count | File |\n|---------|-------|------|\n| [Ethereum](docs/networks/mainnet.md) | 2,484 | Largest ecosystem |\n| [Base](docs/networks/base.md) | 1,841 | Fast-growing L2 |\n| [BSC](docs/networks/bsc.md) | 1,670 | BNB Chain |\n| [Arbitrum](docs/networks/arbitrum-one.md) | 1,437 | Leading L2 |\n| [Polygon](docs/networks/matic.md) | 1,304 | Polygon PoS |\n| [Optimism](docs/networks/optimism.md) | 580 | OP Stack L2 |\n| [Avalanche](docs/networks/avalanche.md) | 453 | C-Chain |\n\nFull index: [`docs/NETWORKS.md`](docs/NETWORKS.md)\n\n### Protocol Types\n\n| Type | Count | Description |\n|------|-------|-------------|\n| DEX | 4,411 | Uniswap, Sushi, Curve, Balancer, PancakeSwap |\n| Lending | 1,469 | Aave, Compound, Morpho, Spark, Silo |\n| Staking | 898 | Lido, Rocket Pool, EigenLayer, Graph Network |\n| Bridge | 836 | Hop, Stargate, Across, Wormhole, LayerZero |\n| NFT Marketplace | 450 | OpenSea, Blur, Rarible, Foundation |\n| Yield Aggregator | 425 | Yearn, Beefy, Harvest, Convex |\n| Governance | 425 | Snapshot, Tally, Compound Governor |\n| Perpetuals | 273 | GMX, Gains, dYdX, Hyperliquid |\n| Name Service | 227 | ENS, Space ID, Unstoppable Domains |\n| Options | 192 | Premia, Dopex, Lyra, Hegic |\n\n---\n\n## Reliability Score\n\nEach subgraph gets a composite reliability score (0-1) based on four on-chain signals:\n\n| Signal | Weight | What it measures |\n|--------|--------|------------------|\n| **Query Fees** | 30% | GRT fees earned from actual usage |\n| **Query Volume** | 30% | 30-day query count |\n| **Curation Signal** | 20% | GRT tokens curated by the community |\n| **Indexer Allocation** | 20% | GRT allocated to this subgraph by indexers |\n\nAll values are log-scaled and capped at 1.0. A 0.5 penalty is applied if the subgraph has been denied/deprecated.\n\n**Score tiers:** High (0.7+) = strong signal, real usage | Medium (0.3-0.7) = functional, some activity | Low (<0.3) = minimal signal or test deployment\n\n### The score measures traction, so it measures age\n\nAll four inputs are cumulative — fees and curation accrue, volume needs 30 days\nto exist at all. A subgraph deployed last month therefore scores near zero no\nmatter how good it is. Measured on the current corpus (served, non-denied):\n\n| Age | Count | Avg reliability |\n|-----|-------|-----------------|\n| < 30 days | 64 | 0.107 |\n| 30–90 days | 227 | 0.143 |\n| 90–365 days | 1,100 | 0.225 |\n| > 1 year | 4,034 | 0.313 |\n\nThe newest subgraph anywhere in the registry's top 25 is **280 days old** — yet\n59 of those 64 sub-30-day subgraphs are already serving real query volume.\n\nRather than reweight the score and trade a measurable signal for a guess,\n`search_subgraphs` returns young matches in a **separate `emerging` list**\nalongside an `emerging_caveat` explaining that a low score at that age is\nexpected rather than damning. Every result also carries `age_days` and\n`maturity` (`new` < 30d, `emerging` < 90d, `established`). This matters most\nfor new chains and new protocols, where no mature deployment *can* exist —\nsearching \"perpetual futures\" surfaces years-old Ethereum and BSC deployments\nin the main list and the 40-day-old Monad perps subgraph under `emerging`.\n\n`semantic_search_subgraphs` ranks by cosine similarity rather than reliability,\nso it is already age-neutral — it carries the `maturity` labels but no\n`emerging` list, because a three-week-old subgraph can top it on merit.\n\n### Ranking\n\nThree tools rank, and each ranks differently on purpose:\n\n- **`search_subgraphs`** — orders by how many of your query terms matched, then\n by reliability. OR-ing the terms and ordering on reliability alone meant a\n popular subgraph matching one incidental word beat a precise match on all\n three, so being *more* specific returned worse answers. Version tokens\n (`v2`, `v3`, `v4`) are kept rather than dropped as too short.\n- **`semantic_search_subgraphs`** — orders by `semantic_score × (0.5 + 0.5 ×\n reliability)`. Pure cosine put testnets first, since their text is nearly\n identical to mainnet's. The 0.5 floor keeps new subgraphs competitive.\n- **`recommend_subgraph`** — infers domain and protocol type from the goal, but\n as a *ranking bonus*, never a filter. As a filter, one bad keyword collapsed\n the candidate pool to nothing.\n\nA term matching a subgraph's **name** counts for more than one matching its\ndescription — `%ens%` also matches \"tok**ens**\", so equal weighting handed a\nsearch for `ens` to four Uniswap subgraphs.\n\nChain names are aliased, so `ethereum`, `arbitrum`, `polygon` and `bnb` resolve\nto the corpus values `mainnet`, `arbitrum-one`, `matic` and `bsc`.\n\n### Testnets\n\n723 of the 5,425 served subgraphs are on testnets, and their text is nearly\nidentical to their mainnet twins', so they compete for the top slot. They are\n**excluded by default** and every result carries `testnet: true|false`. Pass\n`include_testnets: true` to see them — and an explicit request for a testnet\nnetwork (`network: \"sepolia\"`) always wins over the default, so that still\nreturns exactly what you asked for.\n\n## Using the registry from payql\n\n[`payql`](https://www.npmjs.com/package/payql) can use this registry as its\nfree discovery source instead of paying for a network-subgraph query. Run the\nregistry's HTTP transport and point payql at it:\n\n```bash\nnpx subgraph-registry-mcp --http-only # serves :3848\nPAYQL_REGISTRY_URL=http://127.0.0.1:3848/graphql npx -y payql\n```\n\n`POST /graphql` answers in the Graph network subgraph's `subgraphMetadataSearch`\nshape, which is what payql already parses — so this needs no change on payql's\nside, and discovery becomes free and locally-ranked.\n\n### Denied deployments\n\nCuration-denied deployments (`deniedAt > 0` — denied indexing rewards, usually\nspam, duplicates or deprecations) are **excluded by default** from\n`search_subgraphs`, `semantic_search_subgraphs` and `recommend_subgraph`. Pass\n`include_denied: true` to the two search tools to see them; every result then\ncarries `denied: true|false` so the choice stays visible.\n\n---\n\n## MCP Server\n\nThe registry is available as an MCP server with **dual transport** — stdio for local clients and SSE/HTTP for remote agents.\n\nSame abilities as [graphops/subgraph-mcp](https://github.com/graphops/subgraph-mcp) (hosted SSE `https://subgraphs.mcp.thegraph.com/sse`), **better discovery**. Schema, execute, contract-lookup and 30-day counts use the **official tool names** so an agent can swap connectors. Search stays on our names (`search_subgraphs`, `recommend_subgraph`, `semantic_search_subgraphs`) because they already beat official `search_subgraphs_by_keyword` (reliability, real `query_volume_30d`, network).\n\nOfficial workflow says ALWAYS call `get_deployment_30day_query_counts` before selecting. **Skip that extra round-trip here** — every search/recommend hit already carries `query_volume_30d`. The counts tool still exists under the official name and reads those same registry figures. Official counts have been observed returning 0 for ENS, Lido and Uniswap; we do not copy those zeros.\n\n\n> The shipped server is the Node implementation in [`src/index.js`](src/index.js); that's what `npx subgraph-registry-mcp` runs and what's published to npm. A Python equivalent in [`python/mcp_server.py`](python/mcp_server.py) is kept for local development against the same SQLite database — bug fixes and new tools should land in the Node version first.\n\n**Discovery tools (never execute GraphQL, never introspect live schemas):**\n- **search_subgraphs** — filter by domain, network, protocol type, entity, or keyword. Ranked by matched terms, reliability and real `query_volume_30d`.\n- **recommend_subgraph** — natural language goal to best subgraphs (includes `schema_stable_days`)\n- **semantic_search_subgraphs** — vector-similarity search over precomputed embeddings (sentence-transformers/all-MiniLM-L6-v2, 384-dim). Use for fuzzy/paraphrased goals where literal keyword match would miss.\n- **get_subgraph_detail** — full classification for a specific subgraph (includes `schema_changed_at` and crawled `contract_addresses`)\n- **list_registry_stats** — registry overview (domains, networks, counts)\n- **get_schema_changes** — chronological schema-fingerprint history for a subgraph (one row per detected change). Helps agents prefer mature subgraphs whose data contract has been stable.\n\n**Opt-in query / schema (caller must invoke; search never auto-queries). Official names for connector swap-in:**\n- **execute_query_by_subgraph_id** / **execute_query_by_deployment_id** / **execute_query_by_ipfs_hash** — POST GraphQL to The Graph gateway. Same routing as official (`subgraphs/id` vs `deployments/id`). Requires `THE_GRAPH_STUDIO_API_KEY` (or `GATEWAY_API_KEY`). Without a key, returns `{error: credentials_required, query_url, query_url_x402, hint}` immediately — no hang, no x402 auto-pay. Convenience superset: **execute_query** accepts `id` OR `deployment_id` OR `ipfs_hash`.\n- **get_schema_by_subgraph_id** / **get_schema_by_deployment_id** / **get_schema_by_ipfs_hash** — local `registry_schema` (entities, example_query, fingerprint) with no network when the subgraph is in the corpus; live `__schema` introspection only when a Studio key is set. Convenience superset: **get_schema**.\n- **get_top_subgraph_deployments(contract_address, chain)** — official name. Official `chain` is graph-node ids (`mainnet`, not `ethereum`); we accept both. Top 3 from crawled manifests, ranked by reliability then real 30-day volume (not official query-fees / 0-count oracle). Substreams-powered subgraphs often have no dataSources addresses — that gap is reported, not faked.\n- **get_deployment_30day_query_counts** — official name, `ipfs_hashes` in. Real registry `query_volume_30d`. Unknown hashes return `not_in_registry` rather than a fake 0. Usually unnecessary: the same number is already on every search hit.\n\nSet `THE_GRAPH_STUDIO_API_KEY` in the MCP host env to enable execute/live-schema. No private key is bundled. The keyed gateway often returns HTTP 200 with a GraphQL error body when auth is missing — `execute_query` surfaces `http_status` and `errors` honestly.\n\n### Install\n\n```bash\n# Claude Code\nclaude mcp add subgraph-registry -- npx subgraph-registry-mcp\n\n# Claude Desktop\n{\n \"mcpServers\": {\n \"subgraph-registry\": {\n \"command\": \"npx\",\n \"args\": [\"subgraph-registry-mcp\"],\n \"env\": {\n \"THE_GRAPH_STUDIO_API_KEY\": \"your-studio-key\"\n }\n }\n }\n}\n\n# Remote agents (SSE)\nnpx subgraph-registry-mcp --http-only\n# Then connect to http://localhost:3848/sse\n```\n\nThe server auto-downloads the pre-built registry (8MB SQLite) from GitHub on first run.\n\n---\n\n## Well-Known JSON-LD Manifest\n\nStable, machine-readable per-subgraph manifest that other crawlers and agent frameworks can index without going through MCP. Served by the Node MCP HTTP transport:\n\n```\nGET /.well-known/subgraph/{id}.jsonld Full per-subgraph manifest (JSON-LD)\nGET /subgraphs/{id}.jsonld Alias (same payload)\nGET /.well-known/subgraph-index.jsonld Discovery list — top 100 by reliability with @id links\n```\n\nEach manifest includes classification, parsed entities, contract addresses (from the indexed `dataSources`), endpoints (x402 + API-key), a per-subgraph starter query generated from the actual schema, pricing, and metadata. The `@context` + `@type` make the shape auto-discoverable.\n\n```bash\n# Start the HTTP transport\nnpx subgraph-registry-mcp --http-only\n\n# Fetch the manifest for Uniswap V3 Mainnet\ncurl http://localhost:3848/.well-known/subgraph/5zvR82QoaXYFyDEKLZ9t6v9adgnptxYpKpSbxtgVENFV.jsonld\n```\n\n---\n\n## Semantic Search\n\nEvery subgraph has a precomputed 384-dim embedding from `sentence-transformers/all-MiniLM-L6-v2`, built from its display name, description, canonical entities, top schema entity names, and protocol metadata. At MCP-tool-call time the Node server embeds the query string with the same model (via [@xenova/transformers](https://github.com/xenova/transformers.js), quantized ONNX bundled in the npm package — no first-call download) and ranks rows by cosine similarity.\n\n```js\nconst { subgraphs } = await mcp.call(\"semantic_search_subgraphs\", {\n query: \"lending positions near liquidation on a Layer 2\",\n limit: 5,\n});\n// subgraphs[i].semantic_score is cosine similarity in [0, 1]; >0.5 ~= strong match.\n```\n\nUse it when:\n- The goal is paraphrased or use-case-shaped (`search_subgraphs` is keyword-only).\n- You're exploring \"what data exists for X?\" rather than fetching a specific protocol's subgraph.\n\nSame model is shared between Python crawl-time (`fastembed`) and JS runtime (`@xenova/transformers`) — vectors are bitwise-comparable so cosine math gives consistent rankings across runtimes.\n\nEmbeddings add ~22 MB to `registry.db` (14k × 384 × 4 bytes); model bundle adds ~23 MB to the npm package.\n\n---\n\n## Schema Evolution\n\nEach crawl computes a `schema_fingerprint` (MD5 of sorted `entity:field_count` pairs) per subgraph. Whenever the fingerprint changes from the previous sync, an immutable row is written to `schema_history`. The table is append-only and survives full DB rebuilds.\n\n```js\nconst history = await mcp.call(\"get_schema_changes\", {\n subgraph_id: \"5zvR82QoaXYFyDEKLZ9t6v9adgnptxYpKpSbxtgVENFV\",\n});\n// {\n// total_changes: 3,\n// stable_days: 47.2,\n// changed_within_24h: false,\n// changed_within_7d: false,\n// changes: [\n// { fingerprint: \"abc123...\", prev_fingerprint: \"def456...\", detected_at: 1717... },\n// ...\n// ]\n// }\n```\n\n`recommend_subgraph` and `get_subgraph_detail` results now also include `schema_changed_at` (unix seconds of last detected change) and `schema_stable_days` so agents can prefer subgraphs whose data contract has been stable longer — useful when a query needs to keep working across the agent's planning horizon.\n\n---\n\n## OpenAPI\n\nThe full API surface (MCP tools + REST routes) is published as OpenAPI 3.1:\n\n- `openapi.yaml` — checked into the repo, single source of truth\n- `data/openapi.json` — bundled with the npm tarball\n- `GET /.well-known/openapi.json` — served by the HTTP transport for live discovery\n\nThe spec is regenerated on every release from the declarative `TOOLS[]` + `REST_ROUTES[]` exports in [`src/index.js`](src/index.js) via [`scripts/gen-openapi.js`](scripts/gen-openapi.js). CI fails any PR that touches `src/index.js` without regenerating the spec.\n\n---\n\n## REST API\n\n```\nGET /summary Registry overview and stats\nGET /domains Domain breakdown\nGET /networks Network breakdown\nGET /families Schema family groups (fork/clone detection)\nGET /subgraphs Filter subgraphs\nGET /subgraphs/{id} Full detail for one subgraph (now includes contract_addresses and example_query)\nGET /search?q=uniswap Free-text search\nGET /recommend?goal=...&chain= Agent-optimized recommendation\n```\n\n```bash\n# Start API server\ncd python && python server.py\n\n# Example: find DEX subgraphs on Arbitrum\ncurl \"http://localhost:3847/recommend?goal=query+DEX+trades+on+Arbitrum&chain=arbitrum-one\"\n\n# Example: filter by entity type\ncurl \"http://localhost:3847/subgraphs?entity=liquidity_pool&network=base&min_reliability=0.5\"\n```\n\n---\n\n## Bot-Readable Category Files\n\nThe `docs/` directory contains structured `.md` files with YAML frontmatter designed for AI agents and bots to consume:\n\n```\ndocs/\n├── DOMAINS.md # Index of all domains with counts\n├── NETWORKS.md # Index of all networks with counts\n├── charts/ # Auto-generated SVG visualizations\n│ ├── domains.svg\n│ ├── networks.svg\n│ ├── protocol-types.svg\n│ └── reliability.svg\n├── domains/ # One file per domain\n│ ├── defi.md # Top 25 DeFi subgraphs by reliability\n│ ├── nfts.md\n│ ├── dao.md\n│ └── ...\n└── networks/ # One file per network\n ├── mainnet.md # Top 25 Ethereum subgraphs by reliability\n ├── base.md\n ├── arbitrum-one.md\n └── ...\n```\n\nEach category file includes:\n- YAML frontmatter (domain/network, count, percentage, last updated)\n- Top 25 subgraphs ranked by reliability score\n- MCP tool and REST API query examples\n\n---\n\n## Architecture\n\n```\nGraph Network Subgraph (meta-subgraph, 140M queries/month)\n |\n v\ncrawler.py ---- async httpx, ID-based cursor pagination\n |\n v\nclassifier.py - rule-based domain/protocol classification + schema fingerprinting\n |\n v\nregistry.py --- builds SQLite + indices\n |\n ├── server.py ------ FastAPI REST API (:3847)\n ├── generate_docs.py SVG charts + category .md files\n └── scheduler.py --- weekly incremental sync\n\nMCP Server (src/index.js, published to npm)\n ├── stdio ←── Claude Desktop / Claude Code\n └── SSE ←── OpenClaw / remote agents (:3848)\n\npython/mcp_server.py — local-dev MCP server hitting the same SQLite DB\n```\n\n## Quick Start (Local Build)\n\n```bash\ncd python\npython3 -m venv .venv && source .venv/bin/activate\npip install -r requirements.txt\n\necho \"GATEWAY_API_KEY=your-key-here\" > .env\n\n# Full crawl + classify (~11 min)\npython registry.py\n\n# Generate charts and category files\npython generate_docs.py\n\n# Start API server\npython server.py\n```\n\n## How It Stays Current\n\nA GitHub Actions workflow runs every 3 days:\n1. Incremental crawl (`updatedAt_gte: lastSyncTimestamp`)\n2. Reclassify new/changed subgraphs\n3. Regenerate SVG charts and category .md files\n4. Commit and push updates\n\n## License\n\nMIT\n", "bytes": 22557, "sha": "f99555d5f8e7bc91e39b0b4757511774666ac5bd6810b2cc2f170f65b87c9962", "repo_slug": "paulieb14/subgraph-registry", "fonte": "repo", "truncated": false, "api": "https://agentalog.com/api/listings/mcp_io_github_paulieb14_subgraph_registry_mc_f7863c25/readme" }