Decentralized protocol for indexing EVM (and supported non-EVM) chains via subgraphs. Define schema and mappings, deploy to Subgraph Studio, query a GraphQL gateway.
- 01custom on-chain indexing
- 02GraphQL queries over events
- 03historical aggregations
- 04decentralized / censorship-resistant data
- 05established subgraph ecosystems
- pnpm add -D @graphprotocol/graph-cli
- pnpm add @graphprotocol/graph-ts
- pnpm add graphql graphql-request
| Variable | Scope | Description |
|---|---|---|
| GRAPH_API_KEY | Server | API key issued in Subgraph Studio. Required to query the decentralized gateway. Server-side only. |
| GRAPH_DEPLOY_KEY | Server | Studio deploy key used by `graph deploy` in CI. Treat like a credential. |
Scaffold a subgraph with `graph init`, define `schema.graphql` and event handlers in `src/mapping.ts`, then `graph codegen && graph build` and `graph deploy <subgraph-slug>` to Subgraph Studio. To query: POST GraphQL to `https://gateway.thegraph.com/api/${process.env.GRAPH_API_KEY}/subgraphs/id/<subgraph-id>` using `graphql-request`. Always read the subgraph's `_meta { block { number } }` to detect indexing lag before showing data as authoritative.
- ⚑The legacy Hosted Service was fully shut down — any code or docs referencing `api.thegraph.com/subgraphs/name/...` URLs is dead; you must publish to the decentralized network and query the gateway with an API key.
- ⚑Free tier on the gateway is 100k queries/month per key; bursty frontends should cache or proxy through a server route.
- ⚑Indexer lag is real — a fresh subgraph or one tracking the chain head can be minutes behind; never assume `block.timestamp` from a query equals `now`.
- ⚑Reorgs can cause a deployed subgraph to enter a failed state; handle `_meta { hasIndexingErrors }` and surface a fallback.
- ⚑Non-EVM chain support (Solana, NEAR, etc.) is partial and uneven — verify the chain is supported by the network (not just the codegen) before committing.