How to Build a Graph Subgraph? Deployment, Publishing, and Verification

On-Chain

23 October 2026

Building a The Graph subgraph has one core distinction: deploying and publishing are two separate things. Deploying only pushes your subgraph to Subgraph Studio for testing and staging. Publishing is what puts your subgraph onto the decentralized network so that Indexers and Curators can see it. Many people get stuck wondering "why can't I find any data after deploying?" The reason is often that they never published it, or they published it but did not have enough GRT signal to make Indexers willing to take the work.

OKX Exchange
A leading global cryptocurrency platform,suitable for both beginners and experienced traders.
New user benefit: 20% off trading fees upon registration!！

Prerequisites: Get the Contract and Tools Ready First

Before starting, you need three things: a smart contract that has already been deployed and verified on a block explorer (otherwise the CLI cannot fetch the ABI), Node.js and a package manager installed locally, and a crypto wallet that can connect to Subgraph Studio.

Initialization: Auto-generate the Scaffold from the Contract

After connecting your wallet in Subgraph Studio, create a subgraph. A good naming convention is "SubgraphName ChainName" (for example, MyDapp Ethereum). Once created, the right side of the page will show CLI commands specific to that subgraph, including .

After installing Graph CLI locally, run the graph init --studio command copied from Studio. The CLI will ask for the contract address, network, start block, and more. For Start Block, enter the block height when the contract was deployed. This can significantly reduce indexing time. If you enter 0 or leave it blank, the subgraph will scan from the genesis block, which is much slower. If the contract is verified, the ABI will be fetched automatically. If not, you will need to provide a JSON file manually.

Initialization generates three core files: subgraph.yaml (defines which data sources and events to index), schema.graphql (defines the entities you want to query), and mapping.ts (the logic that converts on-chain events into entities). Your main development work after this is modifying these three files.

Deploy to Studio: Test First, Do Not Rush to Publish

After writing the mapping, run graph codegen (generates types based on the schema) and graph build (compiles). Then copy the deploy command from Studio. First authenticate with graph auth --studio , then deploy with graph deploy --studio . The CLI will ask for a version label. Use semantic versioning (such as 0.0.1) because Curators will see these labels in Graph Explorer and decide whether to signal based on them.

After a successful deployment, run a sample query in Studio's Playground to confirm that entity data is returned. Also check the Dashboard Logs. If there are mapping errors, they will show up here. Studio's test query endpoint has a rate limit (3000 requests per day), which is enough for debugging but not suitable for production.

Publish to the Network: This Step Creates an On-chain Record

Click the Publish button in Studio, select the network, and confirm the publication. Publishing is an on-chain transaction on Arbitrum One, so you need ETH in your wallet to pay for gas. Only after publishing will your subgraph appear in Graph Explorer and Indexers can begin serving it.

Indexers will not come to you automatically. A newly published subgraph has no signal, so Indexers lack economic incentive to index it. The official recommendation is to self-curate with your own GRT at the time of publishing, at least 3,000 GRT to speed up indexing. This number was a recommended value around May 2024. The actual amount of signal needed changes with network conditions, but 3,000 GRT is a starting reference repeatedly cited in multiple documents. If you have no GRT to signal, your subgraph may remain in a "published but no Indexer serving it" state for a long time, and queries will fail or be extremely slow.

Verification: Distinguish Between "Deployment Succeeded" and "Queryable"

Verification happens in stages. You cannot judge everything with one standard.

Studio stage: After deployment, check that Logs show no errors and that Playground queries return data. At this point the data comes from the Upgrade Indexer operated by The Graph Foundation. It is a single point of service and does not mean the decentralized network is ready.

Post-publish stage: Find your subgraph page in Graph Explorer and check the Indexers list and Curation signal amount. If the signal is near zero and the Indexer list is empty, no Indexer has taken it on yet. You can wait or add more GRT signal.

Query verification: Use the API Key created in Studio to send a GraphQL request to the decentralized network query URL. The URL format is https://gateway-arbitrum.network.thegraph.com/api/[api-key]/subgraphs/id/[SUBGRAPH_ID], and the ID is at the top of the Explorer page. If you get indexing_error or a timeout, go back to Explorer and check the indexing status.

One easily overlooked detail: The Graph's smart contracts (GNS, etc.) are all on Arbitrum One, even if your subgraph indexes data from Ethereum, Polygon, or other chains. Gas for publishing and curation is paid in ETH on Arbitrum, not in the native token of the indexed chain.

Updates and Archiving

After modifying a subgraph, redeploying creates a new version. Test it in Studio and then Publish again. Old versions do not disappear automatically, but Graph Explorer will show the latest published version. Unpublished Studio versions have an archiving policy: unpublished versions that are older than 45 days and have not been queried within 30 days will be archived. Also, each time you deploy a new version, the N-2 version of the unpublished subgraph will be archived. If you are just developing and debugging, be careful not to let important versions get automatically cleaned up.