This article applies to:

• Ethereum
• Polygon
• BNB Smart Chain
• Fantom

Introduction

The GraphQL support specification was introduced in Ethereum as part of EIP-1767.

The GraphQL support is implemented in the Go Ethereum (Geth) client. For the latest Geth GraphQL schema, always check the source on Geth GitHub: schema.go.

With Chainstack, you can deploy Geth nodes for the supported EVM-based networks. See Supported protocols.

For an overview of GraphQL and why use GraphQL instead of JSON-RPC, see GraphQL on Ethereum: Availability on Chainstack and a quick rundown.

For the GraphQL endpoint availability on different subscription plans, see Pricing.

For information on how to access your node's GraphQL endpoint, see View node access and credentials.

How to

GraphQL on Geth supports two types of requests:

• Query — a data retrieval request through a Geth GraphQL endpoint.
• Mutation — a request sending a signed raw transaction through a Geth GraphQL endpoint.

Query

Each query has an entrypoint and the fields that can retrieved.

Entrypoints

An entrypoint is the entry into the GraphQL schema and API.

You must always provide and entrypoint for the queries that do not have their own entry objects.

Block

Fetch block by number or by hash.

GraphiQL example

{
  block(number: 13617000)
}

cURL example

curl -H "Content-Type: application/json" -d '{ "query": "{block(number: 13617000){transactionCount}}"}' https://nd-123-456-789.p2pify.com/3c6e0b8a9c15224a8228b9a98ca1531d/graphql

Blocks

Fetches all blocks between specified numbers.

GraphiQL example

{
  blocks(from: 13617000, to: 13617010)
}

cURL example

curl -H "Content-Type: application/json" -d '{ "query": "{blocks(from: 13617000, to: 13617010){ transactionCount}}"}' https://nd-123-456-789.p2pify.com/3c6e0b8a9c15224a8228b9a98ca1531d/graphql

Pending

Fetches the pending state.

GraphiQL example

{
  pending {
    transactionCount
  }
}

cURL example

curl -H "Content-Type: application/json" -d '{ "query": "{pending {transactionCount}}"}' https://nd-123-456-789.p2pify.com/3c6e0b8a9c15224a8228b9a98ca1531d/graphql

Transaction

Fetches the transaction specified by hash.

GraphiQL example

{
  transaction(hash: "0x1e20cd6d47d7021ae7e437792823517eeadd835df09dde17ab45afd7a5df4603")
}

cURL example

curl -H "Content-Type: application/json" -d '{ "query": "{transaction(hash: \"0x1e20cd6d47d7021ae7e437792823517eeadd835df09dde17ab45afd7a5df4603\"){ index }}"}' https://nd-123-456-789.p2pify.com/3c6e0b8a9c15224a8228b9a98ca1531d/graphql

Logs

Fetches log entries matching the provided filter.

GraphiQL example

{
  logs(filter: {fromBlock: 13617000 toBlock: 13617010}) {
    index
    account(block: 13617000) {address: address
    }
  }
}

cURL example

curl -H "Content-Type: application/json" -d '{ "query": "{logs(filter: {fromBlock: 13617000 toBlock: 13617010}) {index account(block: 13617000) {address: address}}}"}' https://nd-123-456-789.p2pify.com/3c6e0b8a9c15224a8228b9a98ca1531d/graphql

GasPrice

Fetches the gas price estimate for a transaction to be mined.

GraphiQL example

{
  gasPrice
}

cURL example

curl -H "Content-Type: application/json" -d '{ "query": "{gasPrice}"}' https://nd-123-456-789.p2pify.com/3c6e0b8a9c15224a8228b9a98ca1531d/graphql

MaxPriorityFeePerGas

Fetches the max gas price estimate for a transaction to be mined.

GraphiQL example

{
  maxPriorityFeePerGas
}

cURL example

curl -H "Content-Type: application/json" -d '{ "query": "{maxPriorityFeePerGas}"}' https://nd-123-456-789.p2pify.com/3c6e0b8a9c15224a8228b9a98ca1531d/graphql

Syncing

Fetches if the node is synced.

GraphiQL example

{
  syncing
}

cURL example

curl -H "Content-Type: application/json" -d '{ "query": "{syncing}"}' https://nd-123-456-789.p2pify.com/3c6e0b8a9c15224a8228b9a98ca1531d/graphql

ChainID

Fetches the chain ID.

GraphiQL example

{
  chainID
}

cURL example

curl -H "Content-Type: application/json" -d '{ "query": "{chainID}"}' https://nd-123-456-789.p2pify.com/3c6e0b8a9c15224a8228b9a98ca1531d/graphql

Queries

Account

Fetches the account state at a block.

• Entrypoint: block.

GraphiQL example

{
  block {
   account(address: "0x1F98431c8aD98523631AE4a59f267346ea31F984") {
     balance
     transactionCount
     code
     storage(slot: "0x0000000000000000000000000000000000000000000000000000000000000000")
   }
  }
}

cURL example

curl -H "Content-Type: application/json" -d '{ "query": "{block {account(address: \"0x1F98431c8aD98523631AE4a59f267346ea31F984\") {balance transactionCount code storage(slot: \"0x0000000000000000000000000000000000000000000000000000000000000000\")}}}"}' https://nd-123-456-789.p2pify.com/3c6e0b8a9c15224a8228b9a98ca1531d/graphql

Access list

Fetches an access list for a transaction in a block. See also EIP-2930.

• Entrypoint: block.

GraphiQL example

{
  block(number: 13617000) {
    transactionAt(index: 77) {
       index
       hash
       type
       accessList {
         address
         storageKeys
       }
     }
   }
}

cURL example

curl -H "Content-Type: application/json" -d '{ "query": "curl -H "Content-Type: application/json" -d '{ "query": "{block(number: 13617000) {transactionAt(index: 77) {index hash type accessList {address storageKeys}}}}"}' https://nd-123-456-789.p2pify.com/3c6e0b8a9c15224a8228b9a98ca1531d/graphql

Call

Executes a local call operation at the current block's state.

• Entrypoint: block.

GraphiQL example

{
  block {
    call(data: {to: "0x1f98431c8ad98523631ae4a59f267346ea31f984", data: "0x13af40350000000000000000000000001a9c8182c09f50c8318d769245bea52c32be35bc"}) {
      data
      status
      gasUsed
    }
  }
}

cURL example

curl -H "Content-Type: application/json" -d '{ "query": "curl -H "Content-Type: application/json" -d '{ "query": "{block {call(data: {to: \"0x1f98431c8ad98523631ae4a59f267346ea31f984\", data: \"0x13af40350000000000000000000000001a9c8182c09f50c8318d769245bea52c32be35bc\"}) {data status gasUsed}}}"}' https://nd-123-456-789.p2pify.com/3c6e0b8a9c15224a8228b9a98ca1531d/graphql

Mutation

Sends a raw signed transaction to the network.

You can use EthereumJS to construct the raw transaction data.

GraphiQL example

mutation {
   sendRawTransaction(data: data)
}

cURL example

curl -H "Content-Type: application/json" --data-raw '{ "query":"mutation {sendRawTransaction(data: \"0x13af40350000000000000000000000001a9c8182c09f50c8318d769245bea52c32be35bc\")}"}' https://nd-123-456-789.p2pify.com/3c6e0b8a9c15224a8228b9a98ca1531d/graphql