Ryan Ghods
Oct 3 · 4 min read

GraphQL is a query language for APIs, which allows you to query large data sets by specifying the format of the expected result. Our large data set will be the Ethereum blockchain and we’ll query it for things like events, client sync status, and transaction data.

Ethereum Grid makes it easy to configure and use Geth, the go-ethereum client, including its GraphQL server via an accessible UI. This quick tutorial will get you started.

Geth serves a GraphiQL interface, accessible within Grid.

Step 1: Download Grid

Grid is a desktop app that makes it easy to download and configure Ethereum tools. Mac, Windows, and Linux builds are available at grid.ethereum.org. Once downloaded and started, Grid will live in your OS menu bar as an Ethereum logo.

Step 2: Configure and Start Geth

Navigate to the Geth plugin in Grid, then, under the “Version” tab, download the latest version of Geth (GraphQL support was introduced in v1.9.0). Note: if you already have Geth installed on your system, this step is still necessary if you want to configure it via Grid. Grid manages binaries locally.

In the “Settings” tab, select the dropdown for Enable GraphQL Server. We’re just exploring, so Görli (testnet) is a good option for the network. Once configured, toggle the switch on to start Geth.

Step 3: Navigate to the GraphiQL Interface

GraphiQL is a fantastic in-browser IDE for exploring and querying GraphQL APIs. Geth makes this interface available at http://localhost:8547, but you can also access it within Grid via the Geth GraphQL Explorer App, which can be found under the “About” tab.

Launch the GraphiQL interface from the About tab.

Step 4: Run Some Queries

Let’s jump into it with some examples.

Querying for Syncing State

This query returns data on the state of your node’s syncing status.

Querying for Events

This query (from the launch post) finds the ENS HashRegistered events on the Görli network and returns the address of the user doing the registration along with the block number and timestamp it was included in.


Use the schema documentation to explore what’s possible (hint: “Docs” button in the upper right corner of GraphiQL). As you begin typing a query, GraphiQL will autocomplete all possible options based on the schema. The example use cases provided by EthQL should prove useful as well.

Bonus: Consuming GraphQL Data

You can build a webapp now that connects to the GraphQL instance running on localhost:8547 and send queries to the /graphql endpoint using a client like Apollo.

If you would like to customize some of the Geth GraphQL flags further, you may click Use custom flags and tweak the following attributes:

--graphql Enable the GraphQL server

--graphql.addr value GraphQL server listening interface (default: “localhost”)

--graphql.port value GraphQL server listening port (default: 8547)

--graphql.corsdomain value Comma separated list of domains from which to accept cross origin requests (browser enforced)

Calling a Contract Function

Executing a contract function can be done by using the call function with the contract’s method signature. A contract’s method signature is the hash of the method you are looking to call, like balanceOf, along with the encoded parameters, like address. You can learn more about Contract ABI and see useful utils to derive the signature from web3.js.

In the below code snippet, I’ll show how to query an ERC20 token balance using the Apollo GraphQL client:

Wrapping Up

In many cases, GraphQL is a stellar alternative to REST APIs. In querying block data, GraphQL’s simple interface is a significant improvement over the JSON-RPC API, giving you exactly the data you need in the format and structure you want it.

Geth’s GraphQL implementation is based on EIP 1767: GraphQL interface to Ethereum node data with efforts led by Consensys’ EthQL team. Keep an eye on them for more exciting developments in additional query fields and types like ERC20 transfers and balances, ENS names, and more.

If you run into any issues or have any suggestions for Grid or our Geth integration, please share your feedback with us. Is there another project you’d like to see integrated within Grid to provide an accessible UI? Let us know!

Ethereum Grid

Ethereum tooling made super-easy

Thanks to Marc Garreau

Ryan Ghods

Written by

Code, UX, and Coffee.

Ethereum Grid

Ethereum tooling made super-easy

Welcome to a place where words matter. On Medium, smart voices and original ideas take center stage - with no ads in sight. Watch
Follow all the topics you care about, and we’ll deliver the best stories for you to your homepage and inbox. Explore
Get unlimited access to the best stories on Medium — and support writers while you’re at it. Just $5/month. Upgrade