Create your first Blockchain GraphQL query

In the previous article, we argued why you should pick GraphQL over REST for blockchain data APIs. In this article, we will cover some basic concepts of GraphQL in the context of Bitquery and build a simple query step by step.

GraphQL Query

A GraphQL query describes the exact data you want, and the result mirrors the shape of the query. For example, this query asks for the latest Ethereum block:

{
  EVM(network: eth) {
    Blocks(limit: {count: 1}, orderBy: {descending: Block_Number}) {
      Block {
        Number
      }
    }
  }
}

The result comes back in the same shape:

{
  "data": {
    "EVM": {
      "Blocks": [
        {
          "Block": {
            "Number": "23514392"
          }
        }
      ]
    }
  }
}

Two things are happening here:

1. We start with a "root" object. In Bitquery's v2 schema this is the blockchain family, for example EVM for Ethereum-compatible chains.
2. We select the data hierarchy based on the schema to get the desired result.

GraphQL Types

GraphQL types are data objects that contain one or multiple fields. In the example above, EVM is a type with a Blocks field, and Block is a type with fields such as Number, Hash, and Time.

GraphQL Type System

GraphQL is a strongly typed language. The type system defines the data types that can be used in a GraphQL application and forms the schema. Every query is validated and executed against that schema.

What is GraphQL schema?

A GraphQL server uses a schema to describe the shape of your data graph. This schema defines a hierarchy of data types with fields.

The schema is a contract between the client and the server. It specifies exactly which queries and subscriptions are available for clients to execute.

How does the schema help you use Bitquery?

The GraphQL schema is the documentation of our APIs.

With the schema, you can search for the types available in the APIs, the fields of those types, and their data formats. The Bitquery IDE has the schema built in: press Ctrl+Space anywhere in a query to see what fields are available at that point, or open the docs panel to browse types.

The Bitquery IDE

The Bitquery IDE is where you will spend most of your time when integrating with Bitquery. It lets you write queries with autocomplete, run them, see results, generate code in several languages, and create the API access token you will use in production.

Creating Queries

Now, let’s create a simple query in the IDE.

Note: Our APIs support more than 40 blockchains, including Bitcoin, Ethereum, Solana, BNB Chain, and Tron. You can query any of them through the same endpoint.

Getting the latest Ethereum blocks

Say we want the details of the latest Ethereum blocks. Here is the step by step process.

• Start with the blockchain family. Ethereum is an EVM chain, so the root is EVM with a network argument:

{
  EVM(network: eth) {
  }
}

At this point the IDE shows a validation error, because GraphQL is strongly typed and we have not selected any field yet.

• Use autocomplete to find the Blocks field, then select the block fields we want. Let's start with just the number:

{
  EVM(network: eth) {
    Blocks {
      Block {
        Number
      }
    }
  }
}

• Before running this, limit the results. Without a limit you would pull far more blocks than you need:

{
  EVM(network: eth) {
    Blocks(limit: {count: 10}) {
      Block {
        Number
      }
    }
  }
}

• We want the latest blocks, not the oldest, so sort by block number in descending order:

{
  EVM(network: eth) {
    Blocks(limit: {count: 10}, orderBy: {descending: Block_Number}) {
      Block {
        Number
      }
    }
  }
}

• To get more details, just add fields. Check the Block type in the schema to see everything you can query:

{
  EVM(network: eth) {
    Blocks(limit: {count: 10}, orderBy: {descending: Block_Number}) {
      Block {
        Number
        Time
        Hash
        TxCount
        BaseFee
      }
    }
  }
}

• Once your query works, use it programmatically in your application. The endpoint is https://streaming.bitquery.io/graphql for all queries, and requests are authorized with an Authorization: Bearer <token> header. You can generate the access token from account.bitquery.io or through the IDE. See the authorization docs for the steps.

From query to stream

One more thing worth knowing: any query like the one above can become a real-time stream. Replace the implicit query keyword with subscription, remove the limit, and run it over WebSocket. The server then pushes every new block to you as it is produced. For high-volume pipelines, Bitquery also offers Kafka and gRPC streams.

Using examples to create queries

If you want more examples, check the Bitquery docs, which contain ready-made queries for blocks, transfers, DEX trades, NFTs, and more across every supported chain. Each example links to the IDE, so you can open it, run it, and modify it to get the result you want.

Wrapping Up

Using GraphQL, you can write expressive queries to get the exact data you want. Use the schema and the IDE's autocomplete to discover what data is available.

In the next article, we will talk about how to use arguments in your GraphQL queries.

If you have any questions or need help with queries, just hop on our Telegram channel. Also, let us know if you are looking for blockchain data APIs.

You might also be interested in:

• API to get Ethereum Smart Contract Events
• Why GraphQL is better for blockchain data APIs
• APIs to get Latest Uniswap Pair Listing
• Simple rest APIs to get Uniswap data (DEX Data APIs)
• API to Get Ethereum Token Balance
• Simple API To Get Ethereum Supply And Data
• Who is actually using Ethereum?
• How to get newly created Ethereum Tokens?
• Querying Binance Smart Chain (BSC)

About Bitquery

Bitquery provides blockchain data APIs and streams across more than 40 chains. The current lineup includes GraphQL APIs and subscriptions for historical and real-time data, Kafka and gRPC data streams for low-latency pipelines, an MCP server that lets AI agents query on-chain data directly, and Coinpath MoneyFlow for fund-flow tracing and investigations.

If you have any questions about our products, ask them on our Telegram channel. Also, subscribe to our newsletter below, we will keep you updated with the latest in the cryptocurrency world.