Overview

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

Authentication

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 Authentication 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	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:

Chain	Network	Cluster ID
Hyperliquid	Mainnet	hyperliquid-core-mainnet

Example Request:

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

Example Response:

[
  {
    "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	Type	Required	Description
query	string	Yes	The SQL query to execute
clusterId	string	Yes	The blockchain network identifier (e.g., "hyperliquid-core-mainnet")

Example Request:

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:

• meta: Array of column metadata with name and type for each column in the result set
• data: Array of objects containing the actual query results, with each object representing one row
• rows: Number of rows returned in this response
• rows_before_limit_at_least: Total number of rows that matched the query before applying LIMIT (useful for pagination)
• statistics: Performance metrics for query optimization:
  • elapsed: Total query execution time in seconds
  • rows_read: Total number of rows scanned during execution (may be more than returned rows due to filtering)
  • bytes_read: Total data scanned in bytes (helpful for understanding query cost and optimization opportunities)

Example Response:

{
    "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
    }
}

---

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, GROUP BY, aggregations, JOIN 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.

We ❤️ Feedback!

If you have any feedback or questions about this documentation, let us know. We'd love to hear from you!