Bitquery Getting Started: Account, Keys, First Query (2026)

Getting started overview

This guide outlines the steps for initiating development with Bitquery's GraphQL APIs. It covers account creation, API key generation, and executing a foundational GraphQL query. Bitquery provides access to indexed blockchain data across multiple networks, including Ethereum, Binance Smart Chain, Polygon, and Avalanche Bitquery supported blockchains. The primary interaction method is via a GraphQL endpoint, which allows for flexible data retrieval based on specific query requirements Bitquery GraphQL API explorer.

The process generally involves:

1. Signing up for a Bitquery account.
2. Generating an API key from the user dashboard.
3. Constructing a GraphQL query.
4. Sending the query to the Bitquery GraphQL endpoint with the API key for authentication.

Quick reference table

Create an account and get keys

Accessing Bitquery's APIs requires an active account and an API key. This key authenticates your requests and tracks your API credit usage.

Account creation

1. Navigate to the Bitquery pricing page.
2. Select a plan. The Developer Plan offers 50,000 credits per month free of charge, which is suitable for getting started Bitquery pricing tiers.
3. Follow the prompts to complete the registration process, which typically involves providing an email address and creating a password.
4. Verify your email address if prompted.

API key generation

After successfully creating and logging into your account:

1. Access your Bitquery user dashboard.
2. Locate the 'API Keys' section, typically found in the sidebar or settings menu.
3. Click on a button to generate a new API key. Bitquery issues a unique alphanumeric string.
4. Copy this API key immediately. It is usually displayed only once for security reasons. Store it securely, as it will be used to authenticate all your API requests.

Your API key identifies your application and ensures that your requests are authorized. It should be treated as sensitive information, similar to a password. Best practices for handling API keys include using environment variables for storage rather than hardcoding them directly into your application's source code AWS best practices for access keys.

Your first request

With an API key in hand, you can now construct and execute your first GraphQL query. This example demonstrates fetching the latest blocks for a specific blockchain, such as Ethereum.

GraphQL endpoint

All Bitquery GraphQL API requests are sent to a single endpoint:

https://graphql.bitquery.io/

Example query: latest Ethereum blocks

This query retrieves the first 10 latest blocks on the Ethereum blockchain, including their hash, height, and timestamp.

query { 
  ethereum(network: ethereum) { 
    blocks(options: {limit: 10, desc: "height"}) { 
      hash
      height
      timestamp { 
        time
      }
    }
  }
}

Making the request

You can use various tools and programming languages to send this GraphQL query. The API key must be included in the X-API-KEY HTTP header.

Using cURL

cURL is a command-line tool for making HTTP requests.

curl -X POST \
  -H "Content-Type: application/json" \
  -H "X-API-KEY: YOUR_API_KEY" \
  --data '{ "query": "query { ethereum(network: ethereum) { blocks(options: {limit: 10, desc: \"height\"}) { hash height timestamp { time } } } }" }' \
  https://graphql.bitquery.io/

Replace YOUR_API_KEY with your actual API key.

Using JavaScript (Fetch API)

For client-side or Node.js applications, the Fetch API can be used.

const API_KEY = 'YOUR_API_KEY';
const query = `
  query {
    ethereum(network: ethereum) {
      blocks(options: {limit: 10, desc: "height"}) {
        hash
        height
        timestamp {
          time
        }
      }
    }
  }
`;

fetch('https://graphql.bitquery.io/', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'X-API-KEY': API_KEY,
  },
  body: JSON.stringify({ query }),
})
.then(response => response.json())
.then(data => console.log(data))
.catch(error => console.error('Error:', error));

Remember to substitute YOUR_API_KEY with your API key.

Using Python (requests library)

Python's requests library simplifies HTTP requests.

import requests
import json

API_KEY = 'YOUR_API_KEY'
query = """
query {
  ethereum(network: ethereum) {
    blocks(options: {limit: 10, desc: "height"}) {
      hash
      height
      timestamp {
        time
      }
    }
  }
}
"""

headers = {
    'Content-Type': 'application/json',
    'X-API-KEY': API_KEY
}

response = requests.post('https://graphql.bitquery.io/', headers=headers, data=json.dumps({'query': query}))

if response.status_code == 200:
    print(json.dumps(response.json(), indent=2))
else:
    print(f"Error: {response.status_code} - {response.text}")

Replace YOUR_API_KEY with your API key.

Expected response

A successful response will return a JSON object containing the requested block data:

{
  "data": {
    "ethereum": {
      "blocks": [
        {
          "hash": "0x...",
          "height": 19999999,
          "timestamp": {
            "time": "2026-05-29T12:00:00Z"
          }
        },
        // ... more blocks
      ]
    }
  }
}

Common next steps

After successfully making your first request, consider these common next steps to further integrate with Bitquery:

• Explore the GraphQL Playground: The Bitquery GraphQL Playground provides an interactive environment to build and test queries directly in your browser. It offers schema introspection, query validation, and documentation for available fields and types.
• Consult the Documentation: The Bitquery documentation offers comprehensive guides on various blockchain data, advanced querying techniques, and specific use cases like DeFi and NFT data.
• Implement Error Handling: Integrate robust error handling into your application to manage potential issues such as invalid API keys, rate limits, or malformed queries. GraphQL responses typically include an errors array for detailed error information GraphQL over HTTP specification.
• Monitor API Usage: Keep track of your API credit consumption through your Bitquery dashboard to ensure you stay within your plan's limits.
• Explore Advanced Queries: Experiment with more complex queries, such as filtering by specific addresses, time ranges, or transaction types. Bitquery supports a wide range of filters and aggregations to refine your data retrieval Bitquery GraphQL examples.
• Integrate into Applications: Begin integrating Bitquery data into your decentralized applications (dApps), analytics dashboards, or research tools.

Troubleshooting the first call

If your first API call doesn't return the expected data, consider these common issues and troubleshooting steps:

• Invalid API Key: Double-check that the API key in your request's X-API-KEY header exactly matches the key generated in your Bitquery dashboard. Even minor typos or extra spaces can cause authentication failures.
• Missing API Key Header: Ensure the X-API-KEY header is present in your request. Without it, Bitquery cannot authenticate your request.
• Incorrect Endpoint: Verify that you are sending the request to the correct GraphQL endpoint: https://graphql.bitquery.io/.
• Malformed GraphQL Query: GraphQL queries must adhere to the specific syntax. Use the Bitquery GraphQL Playground to validate your query syntax before sending it via code. The playground often provides immediate feedback on syntax errors.
• Content-Type Header: For POST requests with a JSON body, the Content-Type: application/json header is required. Ensure this is correctly set.
• Network Issues: Confirm that your internet connection is stable and that there are no firewall rules blocking outgoing requests to graphql.bitquery.io.
• Rate Limits: If you are on a free tier or have exceeded your plan's limits, Bitquery may return an error indicating rate limiting. Check your dashboard for current usage and plan details.
• Server-Side Errors: Occasionally, the Bitquery API may experience temporary issues. If all other checks pass, consult the Bitquery Changelog or status page for any reported outages.
• Check Response for Errors Array: GraphQL responses include an errors array in the JSON body for detailed error messages, even if the HTTP status code is 200. Parse this array to understand specific issues with your query or request MDN HTTP Status Codes.