The Graph is a decentralized protocol for indexing and querying blockchain data. The Graph makes it possible to query data that is difficult to query directly.

Projects with complex smart contracts like Uniswap and NFTs initiatives like Bored Ape Yacht Club store data on the Ethereum blockchain, making it really difficult to read anything other than basic data directly from the blockchain.

In the case of Bored Ape Yacht Club, we can perform basic read operations on the contract like getting the owner of a certain Ape, getting the content URI of an Ape based on their ID, or the total supply, as these read operations are programmed directly into the smart contract, but more advanced real-world queries and operations like aggregation, search, relationships, and non-trivial filtering are not possible. For example, if we wanted to query for apes that are owned by a certain address, and filter by one of its characteristics, we would not be able to get that information by interacting directly with the contract itself.

To get this data, you would have to process every single transfer event ever emitted, read the metadata from IPFS using the Token ID and IPFS hash, and then aggregate it. Even for these types of relatively simple questions, it would take hours or even days for a decentralized application (dapp) running in a browser to get an answer.

You could also build out your own server, process the transactions there, save them to a database, and build an API endpoint on top of it all in order to query the data. However, this option is resource intensive, needs maintenance, presents a single point of failure, and breaks important security properties required for decentralization.

To put it simply, indexing blockchain data is really, really hard.

Blockchain properties like finality, chain reorganizations, or uncled blocks complicate this process further, and make it not just time consuming but conceptually hard to retrieve correct query results from blockchain data.

The Graph solves this with a decentralized protocol that indexes and enables the performant and efficient querying of blockchain data. These APIs (indexed "subgraphs") can then be queried with a standard GraphQL API. In the diagram above The Graph sits as a middleware between the blockchain and our application.

The Graph currently supports indexing data from over 40 different networks including Ethereum, NEAR, Arbitrum, Optimism, ZkSync, Polygon, Avalanche, Celo, Fantom, Moonbeam, IPFS, Cosmos Hub and PoA with more networks coming soon. Tens of thousands of developers use The Graph for applications such as Uniswap, Synthetix, KnownOrigin, Art Blocks, Gnosis, Balancer, Livepeer, DAOstack, Audius, Decentraland, and many others.

The Graph learns what and how to index Ethereum data based on subgraph descriptions, known as the subgraph manifest. The subgraph description defines the smart contracts of interest for a subgraph, the events in those contracts to pay attention to, and how to map event data to data that The Graph will store in its database.


Once you have written a subgraph manifest, you use the 

 to store the definition in IPFS and tell the indexer to start indexing data for that subgraph.


This diagram gives more detail about the flow of data once a subgraph manifest has been deployed, dealing with Ethereum transactions:

The Graph must be run alongside a running IPFS node, Ethereum node, and a store (e.g. Postgres). The flow follows these steps:

A dapp adds data to Ethereum through a transaction on a smart contract.

The smart contract emits one or more events while processing the transaction.

 continually scans Ethereum for new blocks and the data for your subgraph they may contain.

Graph Node finds Ethereum events for your subgraph in these blocks and runs the mapping handlers you provided. The mapping is a WASM module written in 

 that creates or updates the data entities that Graph Node stores in response to Ethereum events.

The dapp queries the Graph Node for data indexed from the blockchain, using the node's GraphQL endpoint. The Graph Node in turn translates the GraphQL queries into queries for its underlying data store in order to fetch this data, making use of the store's indexing capabilities. The dapp displays this data in a rich UI for end-users, which they use to issue new transactions on Ethereum. The cycle repeats.

In the following sections we will go into more detail on how to search for existing subgraphs and how to query them for the data you need in your dapp. Before we continue, answer the following quiz questions to continue!

Introduction to The Graph

, or as we like to call it, your decentralized portal into the world of subgraphs and network data. 👩🏽‍🚀 The Graph Explorer consists of multiple parts where you can interact with other subgraph developers, dapp developers, Curators, Indexers, and Delegators.

First things first, if you just finished deploying and publishing your subgraph in the Subgraph Studio, the Subgraphs tab on the top of the navigation bar is the place to view your own finished subgraphs (and the subgraphs of others) on the decentralized network. Here, you’ll be able to find the exact subgraph you’re looking for based on the date created, signal amount, or name.

The Graph currently supports creating subgraphs on Ethereum mainnet and Arbitrum One. You can choose which network on the top right hand corner next to the Connect button.

When you click into a subgraph, you’ll be able to test queries in the playground and be able to leverage network details to make informed decisions. You’ll also be able to signal GRT on your own subgraph or the subgraphs of others to make indexers aware of its importance and quality. This is critical because signaling on a subgraph will incentivize indexers to start indexing its data, which means that it’ll surface on the network to eventually serve queries.


You will also be able to see all of the previously deployed versions, network it is deployed and the indexing progress.

On each subgraph’s dedicated page, several details are surfaced. We will go into these into more detail but these include the following functionality:


View more details such as charts, current deployment ID, and other metadata

Switch versions to explore past iterations of the subgraph

View the Indexers that are indexing on a certain subgraph

Subgraph stats (allocations, Curators, etc)

View the entity who published the subgraph

Under the query tab you can explore the GraphQL API for the subgraph by issuing queries and also viewing the schema.


An example is provided below, but please see the Query API for a complete reference on how to query the subgraph's entities. The playground provides the following features.


History, which shows all your previous queries

Query explorer provides an interactive way to build out your query

If you scroll down to the bottom of the Query tab you will see the Query Quick Start which gives you detailed examples of how to query your subgraph.

Each subgraph published to the decentralized Graph Explorer has a unique query URL that you can find by navigating to the subgraph query page and clicking on the "Query" button on the top right corner. This will open a side pane that will give you the unique query URL of the subgraph as well as some instructions about how to query it.

As you can notice, this query URL must use a unique 

. You can create and manage your API keys in the Subgraph Studio in the "API Keys" section. Learn more about how to use Subgraph Studio 

Querying subgraphs using your API keys will generate query fees that will be paid in GRT.

The About tab contains user configured information about the subgraph, such as a description, the url for the dapp, github link along with other details generated on deployment. Query fees are also displayed on the right side of the page.

Indexers are the backbone of the protocol, being the ones that stake on subgraphs, index them, and serve queries to anyone consuming subgraphs.

Curators analyze subgraphs to identify which subgraphs are of the highest quality. Once a Curator has found a potentially attractive subgraph, they can curate it by signaling on its bonding curve. In doing so, Curators let Indexers know which subgraphs are high quality and should be indexed.

Regardless of whether you’re a dapp developer or a subgraph developer, you’ll need to manage your API keys. This is important for you to be able to query subgraphs because API keys make sure the connections between application services are valid and authorized. This includes authenticating the end user and the device using the application.


Clicking "Manage API Keys" on the "Query" tab will redirect you to the page to manage your keys. This can also be found on the top page of Subgraph Studio. If you are not signed in with your wallet you will be prompted to do so.

At the time of writing this guide the following options are available:

Once you connect your wallet you will be prompted to do the following steps:

Sign a transaction to prove access to the connected wallet

Add an email address for your account on The Graph Explorer

After completing these steps you will be able to create your first API Key.

Simply click Create API Key and you then will be able to:

Optionally, enable period spending limits

Once you have created an API Key you can open it to see the the following details:

Clicking your API Key and then the Security Tab you can optionally:

Add authorized subgraphs your API Key can query

Add restricted domains that can use your API Key

The Graph Explorer

 is the indexing and query layer of web3. Developers build and publish open APIs, called subgraphs, that applications can query using GraphQL. The Graph aims to support the next generation of dapp developers in harnessing the power of blockchain data to bring a superior experience for their users.

There are a number of resources available for you to continue your journey building on The Graph. 