Resumen

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

Autenticación

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.).

Quick Start

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 Autenticación 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:

Punto final	Purpose
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.

Endpoint:

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

Supported Cluster IDs:

Cadena	Red	Cluster ID
Hiperlíquido	Red principal	hyperliquid-core-mainnet

Ejemplo de solicitud:

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

Ejemplo de respuesta:

[
  {
    "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.

Endpoint:

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

Request Parameters:

Parameter	Tipo	Required	Descripción
consulta	cadena	Sí	The SQL query to execute
clusterId	cadena	Sí	The blockchain network identifier (e.g., "hyperliquid-core-mainnet")

Ejemplo de solicitud:

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)

Rubí

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:

• meta: Matriz de metadatos de columnas con nombre y tipo para cada columna del conjunto de resultados
• datos: Matriz de objetos que contiene los resultados reales de la consulta, en la que cada objeto representa una fila
• filas: Número de filas devueltas en esta respuesta
• filas_antes_del_límite_como_mínimo: Número total de filas que coincidían con la consulta antes de aplicar LIMIT (útil para la paginación)
• estadísticas: Indicadores de rendimiento para la optimización de consultas:
  • transcurrido: Tiempo total de ejecución de la consulta en segundos
  • filas_leídas: Número total de filas analizadas durante la ejecución (puede ser superior al número de filas devueltas debido a los filtros)
  • bytes_read: Total de datos analizados en bytes (útil para comprender el coste de las consultas y las oportunidades de optimización)

Ejemplo de respuesta:

{
    "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 1000 filas por solicitud. To retrieve larger result sets, use pagination with the LÍMITE y DESPLAZAMIENTO clauses in your SQL queries.

How Pagination Works

Pagination works by:

1. Using LÍMITE to specify the number of rows to return per page (max 1000)
2. Using DESPLAZAMIENTO to skip rows from previous pages
3. Using the filas_antes_del_límite_como_mínimo field in the response to determine if more results exist

Key Response Fields for Pagination:

• filas: Number of rows returned in the current response
• filas_antes_del_límite_como_mínimo: Total number of rows that matched your query before applying LÍMITE. 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
• If rows < LIMIT, you've reached the last page
• If 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:

• Functions: toDateTime(), base58Encode(), countIf(), round(), etc.
• Advanced features: Subqueries, CTEs, window functions, AGRUPAR POR, aggregations, ÚNETE 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.

¡Nos encanta recibir comentarios!

Si tienes algún comentario o pregunta sobre esta documentación, háznoslo saber. ¡Nos encantaría saber tu opinión!