Subgraph Registry

Agent-friendly semantic classification of all subgraphs on The Graph Network.

Pre-computed index of 15,500+ subgraphs with domain classification, protocol type detection, schema fingerprinting, canonical entity mapping, and composite reliability scoring.

The Problem

Agents 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.

What It Does

1. Crawls all active subgraphs from the Graph Network meta-subgraph (subgraphs indexing subgraphs)

2. Fetches the GraphQL schema for every deployment

3. Classifies each subgraph by:

   • Domain: DeFi, NFTs, DAOs, Gaming, Identity, Infrastructure, Social, Analytics

   • Protocol Type: DEX, Lending, Bridge, Staking, Options, Perpetuals, Marketplace, etc.

   • Canonical Entities: Maps schema types to a standard vocabulary (Pool -> liquidity_pool, Swap -> trade, etc.)

   • Schema Family: Groups forks/clones by schema fingerprint

4. Scores reliability (see Reliability Score below)

5. Publishes as JSON registry + SQLite database + REST API

Quick Start

cd python
python3 -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt

# Create .env with your Graph API key
echo "GATEWAY_API_KEY=your-key-here" > .env

# Full crawl + classify (all 15K+ subgraphs, ~11 min)
python registry.py

# Or limit to top N by signal
python registry.py --max 500

# Start API server
python server.py

API Endpoints

GET /summary                    Registry overview and stats
GET /domains                    Domain breakdown
GET /networks                   Network breakdown
GET /families                   Schema family groups (fork/clone detection)
GET /subgraphs                  Filter subgraphs
GET /subgraphs/{id}             Full detail for one subgraph
GET /search?q=uniswap           Free-text search
GET /recommend?goal=...&chain=  Agent-optimized recommendation

Example: Agent Recommendation

curl "http://localhost:3847/recommend?goal=query+DEX+trades+on+Arbitrum&chain=arbitrum-one"

Returns the top subgraphs matching the intent, with reliability scores and query instructions.

Example: Filter by Entity Type

curl "http://localhost:3847/subgraphs?entity=liquidity_pool&network=base&min_reliability=0.5"

Weekly Sync

# Run weekly incremental updates (only fetches new/changed subgraphs)
python scheduler.py

# One-shot incremental
python scheduler.py --once

Architecture

Graph Network Subgraph (meta-subgraph, 140M queries/month)
    |
    v
crawler.py ---- async httpx, ID-based cursor pagination (bypasses 5K skip limit)
    |
    v
classifier.py - rule-based domain/protocol classification + schema fingerprinting
    |
    v
registry.py --- builds JSON registry + SQLite + indices
    |
    v
server.py ----- FastAPI REST API with /recommend endpoint
    |
    v
scheduler.py -- weekly incremental sync via updatedAt filtering

Output

Classification Results (as of March 2026)

Reliability Score

Each subgraph gets a composite reliability score (0–1) based on four on-chain signals:

All values are log-scaled and capped at 1.0. Usage signals (fees + volume) are weighted higher at 60% because they prove real demand. A 0.5 penalty is applied if the subgraph has been denied/deprecated.

What the scores mean:

• 0.7–1.0: High reliability — strong signal, active indexers, real usage (e.g. Uniswap, Aave)

• 0.3–0.7: Moderate — some signal and usage, likely functional

• 0.0–0.3: Low — minimal signal, may be inactive or a test deployment

MCP Server

The registry is available as an MCP server for agent integration. It exposes 4 tools:

• search_subgraphs — filter by domain, network, protocol type, entity, or keyword

• recommend_subgraph — natural language goal to best subgraphs

• get_subgraph_detail — full classification for a specific subgraph

• list_registry_stats — registry overview (domains, networks, counts)

Install via NPM

npx subgraph-registry-mcp

Add to Claude Desktop

{
  "mcpServers": {
    "subgraph-registry": {
      "command": "npx",
      "args": ["subgraph-registry-mcp"]
    }
  }
}

The server auto-downloads the pre-built registry (8MB SQLite) from GitHub on first run — no local build needed.

How It Stays Current

The Graph Network subgraph indexes all subgraph deployments on-chain. The crawler queries updatedAt_gte: lastSyncTimestamp to fetch only what changed since the last run. Weekly syncs keep the registry fresh without full rebuilds.

License

MIT