ProductTutorial

Blockchain GraphQL API: Your First Query in Python, JavaScript and Ruby

Q: What is the Bitquery GraphQL endpoint?

https://streaming.bitquery.io/graphql for queries over HTTPS, and wss://streaming.bitquery.io/graphql for subscriptions over WebSocket. That covers Ethereum, Solana, Tron and the other chains in this guide; each chain's docs page names its endpoint.

Why GraphQL suits blockchain data, how to build your first query in the Bitquery IDE, and how to call it from cURL, Python, JavaScript and Ruby, or skip the code and ask an AI through the MCP server.

By Gaurav Agrawal · Blockchain Intelligence

Cover Image for Blockchain GraphQL API: Your First Query in Python, JavaScript and Ruby

Bitquery serves blockchain data through a GraphQL API. You describe the data you want, send the query to an endpoint, and get back JSON in the same shape as the query. This guide covers why GraphQL fits blockchain data, how to build a first query in the Bitquery IDE, and how to call it from cURL, Python, JavaScript and Ruby.

Why GraphQL for blockchain data

A blockchain node gives you raw blocks, transactions and events. To answer a real question, such as "how much USDT did this wallet receive last month", you have to store that data, index it and add it up. GraphQL on top of an indexed database moves that work to the server.

What you need	With a typical REST API	With GraphQL
Only a few fields	The endpoint returns every field it has	You list the fields you want and get only those
Data from two chains	One call per chain	One query, with an alias for each chain
A new kind of question	Wait for a new endpoint	Write a new query against the same endpoint
Live updates	Poll the endpoint	Run the same query as a subscription over WebSocket

There are trade-offs. Because every request goes to one URL, browser and CDN caching work less well than with REST, and errors come back inside the JSON body rather than only as HTTP status codes.

Here is the multi-chain case. One request returns the latest block on Ethereum and on BNB Chain:

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

Build your first query in the IDE

The Bitquery IDE is where most queries start. It knows the schema, so it autocompletes field names, flags mistakes before you run anything, and shows the docs for every type.

Pick the chain family and network. Ethereum is an EVM chain, so the query starts with EVM(network: eth). Solana and Tron have their own roots, Solana and Tron.
Pick the data. Autocomplete lists what sits under EVM: Blocks, Transactions, Transfers, DEXTrades and more. Choose Blocks, then Block, then the fields you need, such as Number and Time.
Limit and sort. Add limit: {count: 1} so you do not pull thousands of rows, and orderBy: {descending: Block_Number} so the newest block comes first.
Run it. The result mirrors the query: data, then EVM, then a list of Blocks, each with a Block object holding the fields you asked for.
Add fields as you go. Need the transaction count too? Add TxCount under Block and run it again. Nothing else changes.

This is the query the code examples below send:

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

The Bitquery docs hold ready-made queries for blocks, transfers, balances, DEX trades and more on every supported chain, most with a link that opens the query in the IDE.

Get an access token

Every request needs an OAuth access token. Create an application in your Bitquery account, open its token page and generate a token; the token guide shows each step, and also how to request a token from code. Send it in a header with every HTTP request:

Authorization: Bearer <YOUR_ACCESS_TOKEN>

The queries in this guide go to https://streaming.bitquery.io/graphql, as POST requests with a JSON body. Each chain's page in the docs names the endpoint it uses. The IDE can also generate the request code for you in several languages.

Call the API from code

cURL

cURL is the quickest way to test a request from the terminal.

curl -X POST https://streaming.bitquery.io/graphql \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  --data '{"query": "{ EVM(network: eth) { Blocks(limit: {count: 1}, orderBy: {descending: Block_Number}) { Block { Number Time } } } }"}'

Python

This example uses the requests library.

import requests

URL = "https://streaming.bitquery.io/graphql"
TOKEN = "YOUR_ACCESS_TOKEN"


def run_query(query):
    headers = {
        "Content-Type": "application/json",
        "Authorization": f"Bearer {TOKEN}",
    }
    response = requests.post(URL, json={"query": query}, headers=headers)
    if response.status_code == 200:
        return response.json()
    raise Exception(f"Query failed with status {response.status_code}: {response.text}")


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

result = run_query(query)
print(f"Result - {result}")

For subscriptions and async code, gql is a GraphQL client with WebSocket support.

JavaScript

The built-in fetch API, in browsers and in Node.js 18 and later, is all you need.

const query = `
{
  EVM(network: eth) {
    Blocks(limit: {count: 1}, orderBy: {descending: Block_Number}) {
      Block {
        Number
        Time
      }
    }
  }
}
`;

const url = "https://streaming.bitquery.io/graphql";
const opts = {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "Authorization": "Bearer YOUR_ACCESS_TOKEN",
  },
  body: JSON.stringify({ query }),
};

fetch(url, opts)
  .then((res) => res.json())
  .then(console.log)
  .catch(console.error);

For larger apps, graphql-request is a minimal client and Apollo Client adds caching and React integration. graphql-ws handles subscriptions.

Ruby

This example uses only the standard library.

require 'net/http'
require 'uri'
require 'json'

uri = URI.parse("https://streaming.bitquery.io/graphql")
headers = {
  'Content-Type' => 'application/json',
  'Authorization' => 'Bearer YOUR_ACCESS_TOKEN'
}
query = "{ EVM(network: eth) { Blocks(limit: {count: 1}, orderBy: {descending: Block_Number}) { Block { Number Time } } } }"

http = Net::HTTP.new(uri.host, uri.port)
http.use_ssl = true

request = Net::HTTP::Post.new(uri.request_uri, headers)
request.body = { query: query }.to_json

response = http.request(request)
puts "Body: #{response.body}"

For a typed client, see GitHub's graphql-client.

Real-time data: subscriptions and streams

Any query can become a live feed. Change the query keyword to subscription, drop the limit, and send it over WebSocket to wss://streaming.bitquery.io/graphql. WebSocket connections pass the token in the URL rather than in a header, and use the graphql-ws subprotocol; the WebSocket guide has the details. For high-volume pipelines, Kafka and gRPC streams push raw on-chain data without a query loop.

Skip the code: ask an AI

If you only need an answer, not an integration, the Bitquery MCP server connects Claude, ChatGPT or Cursor to the same data. Add https://mcp.bitquery.io as a connector and ask in plain English, for example "Show the latest trades in the Uniswap v3 WETH/USDC pool on Ethereum." The AI picks the tools, runs the queries and shows the rows behind its answer. Plans are on our pricing page.

Frequently asked questions

What is the Bitquery GraphQL endpoint?

https://streaming.bitquery.io/graphql for queries over HTTPS, and wss://streaming.bitquery.io/graphql for subscriptions over WebSocket. That covers Ethereum, Solana, Tron and the other chains in this guide; each chain's docs page names its endpoint.

Do I need a token to use the API?

Yes. Every request needs an OAuth access token from your Bitquery account, sent as Authorization: Bearer <token> over HTTP or as a token parameter in the WebSocket URL.

Why use GraphQL instead of REST for blockchain data?

You ask for exactly the fields you need, combine chains in one request, and turn any query into a live subscription, all through the same endpoint. REST is simpler to cache, which matters less for data that changes every block.

Which languages can call the API?

Any language that can send an HTTPS POST request with a JSON body. This guide shows cURL, Python, JavaScript and Ruby; the GraphQL code page lists clients for many more.