graphql.md

title	sidebar_position	description	tags
Use GraphQL over HTTP	3	How to access the Besu API using GraphQL	public networks private networks

import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem';

Use GraphQL over HTTP

GraphQL can reduce the overhead needed for common queries. For example, instead of querying each receipt in a block, GraphQL can get the same result with a single query for the entire block.

The Besu GraphQL schema describes the GraphQL implementation for Ethereum. Enable the GraphQL service using command line options.

:::note

GraphQL is not supported over WebSocket.

:::

Access the GraphQL endpoint at http://<HOST>:<PORT>/graphql. Configure <HOST> and <PORT> using graphql-http-host and graphql-http-port. The default endpoint is http://127.0.0.1:8547/graphql.

GraphQL requests with cURL

Besu JSON-RPC API methods with an equivalent GraphQL query include a GraphQL request and result in the method example.

For example, the following request returns the block number:

curl -X POST -H "Content-Type: application/json" --data '{ "query": "{block{number}}"}' http://localhost:8547/graphql

{
  "data" : {
    "block" : {
      "number" : "0x281"
    }
  }
}

The following request returns the gas price:

curl -X POST -H "Content-Type: application/json" --data '{ "query": "{gasPrice}"}' http://localhost:8547/graphql

{
  "data" : {
    "gasPrice" : "0x0"
  }
}

The following [`syncing`](../../reference/api/index.md#eth_syncing) request returns data about the synchronization status:

curl -X POST -H "Content-Type: application/json" --data '{ "query": "{syncing{startingBlock currentBlock highestBlock}}"}' http://localhost:8547/graphql

{
  "data" : {
    "syncing" : {
      "startingBlock" : 665,
      "currentBlock" : 3190,
      "highestBlock" : 26395
    }
  }
}

:::info note In some cases, for example, when your node is fully synced, the syncing request returns a `null` response:

{
  "data" : {
    "syncing" : null
  }
}

:::

GraphQL requests with GraphiQL app

The third-party tool, GraphiQL, provides a tabbed interface for editing and testing GraphQL queries and mutations. GraphiQL also provides access to the Besu GraphQL schema from within the app.

Pending

transactionCount and transactions supports the Pending query.

:::info

Besu does not execute pending transactions so results from account, call, and estimateGas for Pending do not reflect pending transactions.

:::

curl -X POST -H "Content-Type: application/json" --data '{ "query": "{pending {transactionCount}}"}' http://localhost:8547/graphql

{
  "data": {
    "pending": {
      "transactionCount": 2
    }
  }
}

curl -X POST -H "Content-Type: application/json" --data '{ "query": "{pending {transactions{hash}}}"}' http://localhost:8547/graphql

{
  "data": {
    "pending": {
      "transactions": [
        {
          "hash": "0xbb3ab8e2113a4afdde9753782cb0680408c0d5b982572dda117a4c72fafbf3fa"
        },
        {
          "hash": "0xf6bd6b1bccf765024bd482a71c6855428e2903895982090ab5dbb0feda717af6"
        }
      ]
    }
  }
}