Aperçu

The SQL Explorer REST API enables you to execute SQL queries programmatically against indexed blockchain data. You can query billions of rows of on-chain data using standard SQL syntax and receive results in JSON format.

You can use SQL Explorer in two ways:

1. With Dashboard: Build and test queries in the UI, then export to API calls
2. with REST APIs: Fetch the schema programmatically and build queries entirely in code

Authentification

All requests to the SQL Explorer REST API require authentication via an API key. The API key must be included in the x-api-key header with every request.

To get your API key:

1. Log in to your Quicknode Dashboard
2. Click on the Profile icon in the top right of the left sidebar
3. Select API Keys from the dropdown menu
4. You can either create a new API key for SQL Explorer by clicking Create API Key, or use an existing API key that has SQL Explorer enabled

Note: This is the same API key system used across all Quicknode products (RPC, Streams, IPFS, etc.).

Démarrage rapide

Here's a complete workflow for using SQL Explorer programmatically:

Step 1: Fetch the Schema

Get available tables and columns for your target chain. Replace {clusterId} with your desired cluster ID (e.g., hyperliquid-core-mainnet for Hyperliquid) and YOUR_API_KEY with the API key you obtained from the Authentification section above. See Schema Endpoint for all supported cluster IDs.

curl https://api.quicknode.com/sql/rest/v1/schema/{clusterId} \
  -H "x-api-key: YOUR_API_KEY"

Alternatively, download static schema files from the Schema Reference page.

Step 2: Build Your SQL Query

Using the schema, construct your query:

SELECT toDateTime(block_time) AS time, action_type, user
FROM hyperliquid_system_actions
WHERE block_time >= now() - INTERVAL 1 DAY
ORDER BY block_time DESC
LIMIT 100

Step 3: Execute the Query

Send to the query endpoint with your target cluster ID (see Query Endpoint for details):

curl -X POST 'https://api.quicknode.com/sql/rest/v1/query' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: YOUR_API_KEY' \
  -d '{
    "query": "SELECT toDateTime(block_time) AS time, action_type, user FROM hyperliquid_system_actions WHERE block_time >= now() - INTERVAL 1 DAY ORDER BY block_time DESC LIMIT 100",
    "clusterId": "{clusterId}"
  }'

Available Endpoints

SQL Explorer provides two REST API endpoints:

Endpoint	Objectif
POST /sql/rest/v1/query	Execute SQL queries and retrieve results
GET /sql/rest/v1/schema/{clusterId}	Fetch database schema (tables, columns, types, sort keys)

Base URL: https://api.quicknode.com

Schema Endpoint

Fetch complete database schema including table names, columns, data types, sort keys, and partition strategies.

Point final :

GET https://api.quicknode.com/sql/rest/v1/schema/{clusterId}

Supported Cluster IDs:

Chaîne	Réseau	Cluster ID
Hyperliquid	Mainnet	hyperliquid-core-mainnet

Exemple de requête :

curl https://api.quicknode.com/sql/rest/v1/schema/hyperliquid-core-mainnet \
  -H "x-api-key: YOUR_API_KEY"

Exemple de réponse :

[
  {
    "chain": "Hyperliquid (HyperCore)",
    "clusterId": "hyperliquid-core-mainnet",
    "tables": [
      {
        "name": "hyperliquid_agents",
        "engine": "SharedReplacingMergeTree",
        "total_rows": 81120375,
        "partition_key": "toYYYYMM(snapshot_time)",
        "sorting_key": ["block_number", "agent"],
        "columns": [
          {
            "name": "agent",
            "type": "FixedString(42)"
          },
          {
            "name": "block_number",
            "type": "UInt64"
          },
          {
            "name": "snapshot_time",
            "type": "DateTime64(6, 'UTC')"
          }
          // ... more columns
        ]
      }
      // ... more tables
    ]
  }
]

Alternative: Download static schema files (no API key required) from the Schema Reference page in JSON or plain text format.

---

Query Endpoint

Execute SQL queries and retrieve results.

Point final :

ARTICLE https://api.quicknode.com/sql/rest/v1/query

Request Parameters:

Paramètre	Type	Required	Description
requête	chaîne de caractères	Oui	The SQL query to execute
clusterId	chaîne de caractères	Oui	The blockchain network identifier (e.g., "hyperliquid-core-mainnet")

Exemple de requête :

cURL

curl -X POST 'https://api.quicknode.com/sql/rest/v1/query' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: YOUR_API_KEY' \
  -d '{
    "query": "SELECT toDateTime(block_time) AS time, action_type, user FROM hyperliquid_system_actions WHERE block_time >= now() - INTERVAL 1 DAY ORDER BY block_time DESC LIMIT 100",
    "clusterId": "{clusterId}"
  }'

JavaScript

var myHeaders = new Headers();
myHeaders.append('accept', 'application/json');
myHeaders.append('Content-Type', 'application/json');
myHeaders.append('x-api-key', 'YOUR_API_KEY');

var requestOptions = {
  method: 'POST',
  headers: myHeaders,
  redirect: 'follow',
  body: JSON.stringify({
    query: 'SELECT toDateTime(block_time) AS time, action_type, user FROM hyperliquid_system_actions WHERE block_time >= now() - INTERVAL 1 DAY ORDER BY block_time DESC LIMIT 100',
    clusterId: '{clusterId}'
  })
};

fetch('https://api.quicknode.com/sql/rest/v1/query', requestOptions)
  .then(response => response.json())
  .then(result => console.log(result))
  .catch(error => console.log('error', error));

Python

import requests
import json

url = "https://api.quicknode.com/sql/rest/v1/query"

payload = json.dumps({
  "query": "SELECT toDateTime(block_time) AS time, action_type, user FROM hyperliquid_system_actions WHERE block_time >= now() - INTERVAL 1 DAY ORDER BY block_time DESC LIMIT 100",
  "clusterId": "{clusterId}"
})

headers = {
  'accept': 'application/json',
  'Content-Type': 'application/json',
  'x-api-key': 'YOUR_API_KEY'
}

response = requests.request("POST", url, headers=headers, data=payload)

print(response.text)

Ruby

require "uri"
require "json"
require "net/http"

url = URI("https://api.quicknode.com/sql/rest/v1/query")

https = Net::HTTP.new(url.host, url.port)
https.use_ssl = true

request = Net::HTTP::Post.new(url)
request["accept"] = "application/json"
request["Content-Type"] = "application/json"
request["x-api-key"] = "YOUR_API_KEY"

request.body = JSON.dump({
  "query": "SELECT toDateTime(block_time) AS time, action_type, user FROM hyperliquid_system_actions WHERE block_time >= now() - INTERVAL 1 DAY ORDER BY block_time DESC LIMIT 100",
  "clusterId": "{clusterId}"
})

response = https.request(request)
puts response.read_body

Response Format:

The API returns a JSON response with query results, metadata, and execution statistics.

Response Fields:

• méta: Tableau de métadonnées de colonnes avec nom et type pour chaque colonne de l'ensemble de résultats
• données: Tableau d'objets contenant les résultats réels de la requête, chaque objet représentant une ligne
• lignes: Nombre de lignes renvoyées dans cette réponse
• nombre_de_lignes_avant_la_limite_au_minimum: Nombre total de lignes correspondant à la requête avant l'application de LIMIT (utile pour la pagination)
• statistiques: Indicateurs de performance pour l'optimisation des requêtes :
  • écoulé: Durée totale d'exécution de la requête en secondes
  • nombre_lignes_lues: Nombre total de lignes analysées lors de l'exécution (ce nombre peut être supérieur au nombre de lignes renvoyées en raison du filtrage)
  • octets_lus: Volume total de données analysées en octets (utile pour comprendre le coût des requêtes et identifier les possibilités d'optimisation)

Exemple de réponse :

{
    "meta": [
        {
            "name": "time",
            "type": "DateTime('UTC')"
        },
        {
            "name": "action_type",
            "type": "LowCardinality(String)"
        }
    ],
    "data": [
        {
            "time": "2026-03-30 18:05:15",
            "action_type": "SystemSpotSendAction",
            "user": "0x2222222222222222222222222222222222222222"
        },
        {
            "time": "2026-03-30 18:05:14",
            "action_type": "SystemSpotSendAction",
            "user": "0x2000000000000000000000000000000000000153"
        }
    ],
    "rows": 100,
    "rows_before_limit_at_least": 14781,
    "statistics": {
        "elapsed": 0.004817085,
        "rows_read": 33599,
        "bytes_read": 1009864
    }
}

Pagination

SQL Explorer limits query results to 1 000 lignes par requête. To retrieve larger result sets, use pagination with the LIMITE et DÉCALAGE clauses in your SQL queries.

How Pagination Works

Pagination works by:

1. Using LIMITE to specify the number of rows to return per page (max 1000)
2. Using DÉCALAGE to skip rows from previous pages
3. Using the nombre_de_lignes_avant_la_limite_au_minimum field in the response to determine if more results exist

Key Response Fields for Pagination:

• lignes: Number of rows returned in the current response
• nombre_de_lignes_avant_la_limite_au_minimum: Total number of rows that matched your query before applying LIMITE. Use this to calculate total pages and determine when to stop paginating.

Basic Pagination Example

To paginate through results in batches of 100 rows:

Page 1 (rows 1-100):

cURL

curl -X POST 'https://api.quicknode.com/sql/rest/v1/query' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: YOUR_API_KEY' \
  -d '{
    "query": "SELECT timestamp, coin, side, price, size, price * size AS notional_usd, buyer_address, seller_address, buyer_fee, seller_fee, fee_token FROM hyperliquid_trades WHERE block_time > now() - INTERVAL 1 HOUR ORDER BY block_number DESC, trade_id DESC LIMIT 100 OFFSET 0",
    "clusterId": "hyperliquid-core-mainnet"
  }'

JavaScript

const pageSize = 100;
const pageNumber = 1;
const offset = (pageNumber - 1) * pageSize;

var myHeaders = new Headers();
myHeaders.append('accept', 'application/json');
myHeaders.append('Content-Type', 'application/json');
myHeaders.append('x-api-key', 'YOUR_API_KEY');

var requestOptions = {
  method: 'POST',
  headers: myHeaders,
  redirect: 'follow',
  body: JSON.stringify({
    query: `SELECT timestamp, coin, side, price, size, price * size AS notional_usd, buyer_address, seller_address, buyer_fee, seller_fee, fee_token FROM hyperliquid_trades WHERE block_time > now() - INTERVAL 1 HOUR ORDER BY block_number DESC, trade_id DESC LIMIT ${pageSize} OFFSET ${offset}`,
    clusterId: 'hyperliquid-core-mainnet'
  })
};

fetch('https://api.quicknode.com/sql/rest/v1/query', requestOptions)
  .then(response => response.json())
  .then(result => {
    console.log(`Page ${pageNumber}: ${result.rows} rows`);
    console.log(`Total matching rows: ${result.rows_before_limit_at_least}`);
  })
  .catch(error => console.log('error', error));

Python

import requests
import json

page_size = 100
page_number = 1
offset = (page_number - 1) * page_size

url = "https://api.quicknode.com/sql/rest/v1/query"

payload = json.dumps({
  "query": f"SELECT timestamp, coin, side, price, size, price * size AS notional_usd, buyer_address, seller_address, buyer_fee, seller_fee, fee_token FROM hyperliquid_trades WHERE block_time > now() - INTERVAL 1 HOUR ORDER BY block_number DESC, trade_id DESC LIMIT {page_size} OFFSET {offset}",
  "clusterId": "hyperliquid-core-mainnet"
})

headers = {
  'accept': 'application/json',
  'Content-Type': 'application/json',
  'x-api-key': 'YOUR_API_KEY'
}

response = requests.request("POST", url, headers=headers, data=payload)
result = response.json()

print(f"Page {page_number}: {result['rows']} rows")
print(f"Total matching rows: {result['rows_before_limit_at_least']}")

Page 2 (rows 101-200):

curl -X POST 'https://api.quicknode.com/sql/rest/v1/query' \
  -H 'accept: application/json' \
  -H 'Content-Type: application/json' \
  -H 'x-api-key: YOUR_API_KEY' \
  -d '{
    "query": "SELECT timestamp, coin, side, price, size, price * size AS notional_usd, buyer_address, seller_address, buyer_fee, seller_fee, fee_token FROM hyperliquid_trades WHERE block_time > now() - INTERVAL 1 HOUR ORDER BY block_number DESC, trade_id DESC LIMIT 100 OFFSET 100",
    "clusterId": "hyperliquid-core-mainnet"
  }'

Pagination Response Example

When using pagination, pay attention to these response fields:

{
  "meta": [...],
  "data": [...],
  "rows": 100,
  "rows_before_limit_at_least": 4567,
  "statistics": {
    "elapsed": 0.042,
    "rows_read": 15847,
    "bytes_read": 2456789
  }
}

• rows: 100 - This page returned 100 rows
• rows_before_limit_at_least: 4567 - At least 4,567 total rows match your query
• Si rows < LIMIT, you've reached the last page
• Si rows_before_limit_at_least > (OFFSET + rows), more pages are available

Working with Queries

Pre-Built Queries

SQL Explorer includes pre-built queries for Hyperliquid covering trading, market analysis, position tracking, and infrastructure monitoring across multiple categories: Trading, Fills, Orders, Funding, Infrastructure, Ledger, Markets, Builders, and Staking.

See all pre-built queries with request and response examples in the Hyperliquid Queries page.

Custom Queries

You can write custom SQL queries beyond the pre-built ones. SQL Explorer supports standard SQL syntax including:

• Fonctions : toDateTime(), base58Encode(), countIf(), round(), etc.
• Advanced features: Subqueries, CTEs, window functions, GROUP BY, aggregations, REJOIGNEZ-NOUS operations

Two Approaches:

1. Dashboard-First: Test queries in the SQL Explorer Dashboard, then click the API button to export as code
2. Code-First: Follow the Quick Start workflow above to build queries programmatically

Building Custom Data APIs:

SQL Explorer lets you execute any SQL query programmatically. Wrap queries in your own backend services to create custom endpoints, build reusable data APIs, or use the same queries across dashboards, mobile apps, and trading bots.

Nous ❤️ les commentaires !

Si vous avez des commentaires ou des questions concernant cette documentation, faites-le nous savoir. Nous serions ravis de vous entendre !