From fc937ad79271ef994554a88b519a2e3e766470e2 Mon Sep 17 00:00:00 2001 From: John Mitsch Date: Fri, 13 Nov 2026 09:38:24 -0500 Subject: [PATCH 1/4] feat(sql): add list_clusters to the core client The SQL Explorer API exposes a public cluster catalog at GET clusters. The request uses the keyless HTTP client so the account API key is not sent and an SDK without a key can call it. --- crates/core/src/lib.rs | 7 +-- crates/core/src/sql/mod.rs | 102 ++++++++++++++++++++++++++++++++++++- 2 files changed, 104 insertions(+), 5 deletions(-) diff --git a/crates/core/src/lib.rs b/crates/core/src/lib.rs index 76774f9..4eb5057 100644 --- a/crates/core/src/lib.rs +++ b/crates/core/src/lib.rs @@ -56,7 +56,7 @@ pub use rpc::{ pub use rpc::{ChannelState, ChannelStatus}; pub use sql::{ ChainSchema, ColumnMeta, ColumnSchema, QueryParams, QueryResponse, QueryStatistics, - SqlApiClient, TableSchema, + SqlApiClient, SqlCluster, TableSchema, }; use reqwest::header::{HeaderMap, HeaderName, HeaderValue}; @@ -285,8 +285,9 @@ pub struct QuicknodeSdk { /// Key-Value Store client: manages sets (single values) and lists /// (ordered collections) under string keys. pub kvstore: kvstore::KvStoreApiClient, - /// SQL Explorer client: executes SQL queries against indexed blockchain - /// data and fetches the database schema. + /// SQL Explorer client: lists the available clusters, executes SQL + /// queries against indexed blockchain data, and fetches the database + /// schema. pub sql: sql::SqlApiClient, /// JSON-RPC client: makes on-chain calls against the account's Tooling /// Access endpoint using short-lived session JWTs. diff --git a/crates/core/src/sql/mod.rs b/crates/core/src/sql/mod.rs index 56fe690..4ad6351 100644 --- a/crates/core/src/sql/mod.rs +++ b/crates/core/src/sql/mod.rs @@ -32,6 +32,31 @@ impl ResolvedSqlConfig { } } +// ── Catalog types ────────────────────────────────────────────────────────── + +/// A cluster that SQL queries can target, as returned by `list_clusters`. +#[cfg_attr(feature = "python", gen_stub_pyclass)] +#[cfg_attr(feature = "python", pyclass(get_all, set_all))] +#[cfg_attr(feature = "node", napi(object))] +#[derive(Debug, Clone, Serialize, Deserialize)] +pub struct SqlCluster { + /// Cluster identifier (e.g. `"hyperliquid-core-mainnet"`); pass it as + /// `cluster_id` to `query` and `get_schema`. + pub id: String, + /// Human-readable name (e.g. `"Hyperliquid (HyperCore)"`). + pub display_name: String, +} + +#[cfg(feature = "python")] +#[gen_stub_pymethods] +#[pymethods] +impl SqlCluster { + #[new] + pub fn new(id: String, display_name: String) -> Self { + Self { id, display_name } + } +} + // ── Request types ────────────────────────────────────────────────────────── /// Parameters for `query`. @@ -232,8 +257,9 @@ impl ChainSchema { // ── Client ───────────────────────────────────────────────────────────────── -/// Client for the Quicknode SQL Explorer. Executes SQL queries against indexed -/// blockchain data and fetches the database schema. +/// Client for the Quicknode SQL Explorer. Lists the available clusters, +/// executes SQL queries against indexed blockchain data, and fetches the +/// database schema. #[derive(Debug, Clone)] pub struct SqlApiClient { config: SdkConfig, @@ -244,6 +270,27 @@ impl SqlApiClient { Self { config } } + /// Lists the clusters available to query. + // The cluster catalog is public, so this uses the keyless client: the + // account `x-api-key` is never sent, and an SDK built without an API key + // can still call it. + pub async fn list_clusters(&self) -> Result, SdkError> { + let url = self.config.sql().base_url.join("clusters")?; + let resp = self + .config + .rpc_http_client() + .get(url) + .send() + .await + .map_err(SdkError::Http)?; + let status = resp.status(); + let body = resp.text().await.map_err(SdkError::Http)?; + if !status.is_success() { + return Err(SdkError::Api { status, body }); + } + serde_json::from_str(&body).map_err(|source| SdkError::Decode { source, body }) + } + /// Executes a SQL query against the given cluster and returns the result /// set. pub async fn query(&self, params: &QueryParams) -> Result { @@ -321,6 +368,57 @@ mod tests { } } + // ── list_clusters ──────────────────────────────────────────────────────── + + #[tokio::test] + async fn list_clusters_success() { + let server = MockServer::start().await; + Mock::given(method("GET")) + .and(path("/clusters")) + // The SDK under test has an API key; the public catalog request + // must not carry it. + .and(|req: &wiremock::Request| !req.headers.contains_key("x-api-key")) + .respond_with(ResponseTemplate::new(200).set_body_json(serde_json::json!([ + {"id": "hyperliquid-core-mainnet", "display_name": "Hyperliquid (HyperCore)"}, + {"id": "solana-mainnet", "display_name": "Solana"} + ]))) + .mount(&server) + .await; + let sdk = make_sdk(format!("{}/", server.uri())); + let clusters = sdk.sql.list_clusters().await.unwrap(); + assert_eq!(clusters.len(), 2); + assert_eq!(clusters[0].id, "hyperliquid-core-mainnet"); + assert_eq!(clusters[0].display_name, "Hyperliquid (HyperCore)"); + assert_eq!(clusters[1].id, "solana-mainnet"); + assert_eq!(clusters[1].display_name, "Solana"); + } + + #[tokio::test] + async fn list_clusters_api_error() { + let server = MockServer::start().await; + Mock::given(method("GET")) + .and(path("/clusters")) + .respond_with(ResponseTemplate::new(500).set_body_string("Internal Server Error")) + .mount(&server) + .await; + let sdk = make_sdk(format!("{}/", server.uri())); + let err = sdk.sql.list_clusters().await.unwrap_err(); + assert!(matches!(err, SdkError::Api { .. })); + } + + #[tokio::test] + async fn list_clusters_decode_error() { + let server = MockServer::start().await; + Mock::given(method("GET")) + .and(path("/clusters")) + .respond_with(ResponseTemplate::new(200).set_body_string("not json")) + .mount(&server) + .await; + let sdk = make_sdk(format!("{}/", server.uri())); + let err = sdk.sql.list_clusters().await.unwrap_err(); + assert!(matches!(err, SdkError::Decode { .. })); + } + // ── query ────────────────────────────────────────────────────────────── #[tokio::test] From aa414cb5151f877621f4286633afa22561964656 Mon Sep 17 00:00:00 2001 From: John Mitsch Date: Fri, 13 Nov 2026 09:45:40 -0500 Subject: [PATCH 2/4] feat(sql): expose list_clusters in the Python, Node, and Ruby bindings Adds SqlCluster to the Python and TypeScript exports and the RBS signature for Ruby. The regenerated type files also pick up an existing gateway_drip doc-comment change that had not been regenerated. --- crates/node/src/lib.rs | 9 ++++ crates/python/src/lib.rs | 12 +++++ crates/ruby/src/lib.rs | 9 ++++ npm/index.d.ts | 18 ++++++- npm/sdk.d.ts | 3 ++ python/quicknode_sdk/__init__.py | 2 + python/quicknode_sdk/__init__.pyi | 2 + python/quicknode_sdk/_core/__init__.pyi | 52 +++++++++++++++---- python/quicknode_sdk/init_manual_override.pyi | 2 + ruby/sig/quicknode_sdk.rbs | 1 + 10 files changed, 99 insertions(+), 11 deletions(-) diff --git a/crates/node/src/lib.rs b/crates/node/src/lib.rs index db6a573..1bd1ea5 100644 --- a/crates/node/src/lib.rs +++ b/crates/node/src/lib.rs @@ -1923,6 +1923,15 @@ pub struct SqlApiClient { #[napi] impl SqlApiClient { + /// Lists the clusters available to query. + #[napi] + pub async fn list_clusters(&self) -> Result> { + self.inner + .list_clusters() + .await + .map_err(errors::map_sdk_err) + } + /// Executes a SQL query against the given cluster and returns the result set. #[napi] pub async fn query(&self, query: String, cluster_id: String) -> Result { diff --git a/crates/python/src/lib.rs b/crates/python/src/lib.rs index 72fb095..ebad514 100644 --- a/crates/python/src/lib.rs +++ b/crates/python/src/lib.rs @@ -3349,6 +3349,17 @@ pub struct SqlApiClient { #[gen_stub_pymethods] #[pymethods] impl SqlApiClient { + /// Lists the clusters available to query. + #[gen_stub(override_return_type( + type_repr = "typing.Coroutine[typing.Any, typing.Any, list[SqlCluster]]" + ))] + fn list_clusters<'py>(&self, py: Python<'py>) -> PyResult> { + let client = self.inner.clone(); + pyo3_async_runtimes::tokio::future_into_py(py, async move { + client.list_clusters().await.map_err(errors::map_sdk_err) + }) + } + /// Executes a SQL query against the given cluster and returns the result /// set. #[pyo3(signature = (query, cluster_id))] @@ -4230,6 +4241,7 @@ fn _core(m: &Bound<'_, PyModule>) -> PyResult<()> { m.add_class::()?; // sql m.add_class::()?; + m.add_class::()?; m.add_class::()?; m.add_class::()?; m.add_class::()?; diff --git a/crates/ruby/src/lib.rs b/crates/ruby/src/lib.rs index 6345a31..820c4f7 100644 --- a/crates/ruby/src/lib.rs +++ b/crates/ruby/src/lib.rs @@ -2494,6 +2494,14 @@ pub struct SqlApiClient { #[allow(clippy::needless_pass_by_value)] impl SqlApiClient { + fn list_clusters(&self) -> Result { + let client = self.inner.clone(); + runtime() + .block_on(client.list_clusters()) + .map_err(map_err) + .and_then(to_ruby) + } + fn query(&self, opts: RHash) -> Result { validate_keys(&opts, &["query", "cluster_id"])?; let client = self.inner.clone(); @@ -3341,6 +3349,7 @@ fn init(ruby: &Ruby) -> Result<(), Error> { // ── Sql ─────────────────────────────────────────────────── let sql = native.define_class("Sql", ruby.class_object())?; + sql.define_method("list_clusters", method!(SqlApiClient::list_clusters, 0))?; sql.define_method("query", method!(SqlApiClient::query, 1))?; sql.define_method("get_schema", method!(SqlApiClient::get_schema, 1))?; diff --git a/npm/index.d.ts b/npm/index.d.ts index 003bb03..1eb2915 100644 --- a/npm/index.d.ts +++ b/npm/index.d.ts @@ -2337,6 +2337,17 @@ export interface SolanaWalletFilterTemplate { accounts: Array } +/** A cluster that SQL queries can target, as returned by `list_clusters`. */ +export interface SqlCluster { + /** + * Cluster identifier (e.g. `"hyperliquid-core-mainnet"`); pass it as + * `cluster_id` to `query` and `get_schema`. + */ + id: string + /** Human-readable name (e.g. `"Hyperliquid (HyperCore)"`). */ + displayName: string +} + export interface SqlConfig { baseUrl?: string } @@ -3647,8 +3658,9 @@ export declare class RpcApiClient { gatewayBuyCredits(session: any, network: string): Promise /** * Requests testnet tokens from the x402 faucet. Resolves to the funding - * transaction `{ accountId, transactionHash }` — NOT a balance; call - * `gatewayCredits` afterwards for that. Allowed once per account. + * transfer metadata containing either `transferId` or `transactionHash`. + * The former is asynchronous Circle settlement; the latter is a direct + * on-chain transfer. This is not a balance; call `gatewayCredits` for that. */ gatewayDrip(session: any): Promise /** @@ -3698,6 +3710,8 @@ export declare class RpcApiClient { } export declare class SqlApiClient { + /** Lists the clusters available to query. */ + listClusters(): Promise> /** Executes a SQL query against the given cluster and returns the result set. */ query(query: string, clusterId: string): Promise /** diff --git a/npm/sdk.d.ts b/npm/sdk.d.ts index 69bc004..effd94f 100644 --- a/npm/sdk.d.ts +++ b/npm/sdk.d.ts @@ -17,6 +17,7 @@ import { HyperliquidWalletEventsFilterTemplate, StellarWalletTransactionsFilterTemplate, RpcApiClient, + SqlCluster, } from "./index"; // Stream destination attributes (input). The inner key is `attributes` rather @@ -410,6 +411,7 @@ export type { // sql SqlConfig, SqlApiClient, + SqlCluster, QueryResponseNode, ColumnMetaNode, QueryStatisticsNode, @@ -572,6 +574,7 @@ export interface QueryResult extends Omit { } export interface SqlApiClientTyped { + listClusters(): Promise; query(query: string, clusterId: string): Promise; getSchema(clusterId: string): Promise; } diff --git a/python/quicknode_sdk/__init__.py b/python/quicknode_sdk/__init__.py index cdaf331..60c3516 100644 --- a/python/quicknode_sdk/__init__.py +++ b/python/quicknode_sdk/__init__.py @@ -221,6 +221,7 @@ GetListResponse, ListContainsItemResponse, SqlApiClient, + SqlCluster, QueryResponse, ColumnMeta, QueryStatistics, @@ -532,6 +533,7 @@ "GetListResponse", "ListContainsItemResponse", "SqlApiClient", + "SqlCluster", "QueryResponse", "ColumnMeta", "QueryStatistics", diff --git a/python/quicknode_sdk/__init__.pyi b/python/quicknode_sdk/__init__.pyi index b1e7b8b..244639a 100644 --- a/python/quicknode_sdk/__init__.pyi +++ b/python/quicknode_sdk/__init__.pyi @@ -223,6 +223,7 @@ from quicknode_sdk._core import ( GetListResponse, ListContainsItemResponse, SqlApiClient, + SqlCluster, QueryResponse, ColumnMeta, QueryStatistics, @@ -550,6 +551,7 @@ __all__ = [ "GetListResponse", "ListContainsItemResponse", "SqlApiClient", + "SqlCluster", "QueryResponse", "ColumnMeta", "QueryStatistics", diff --git a/python/quicknode_sdk/_core/__init__.pyi b/python/quicknode_sdk/_core/__init__.pyi index 7a4a11b..39fd756 100644 --- a/python/quicknode_sdk/_core/__init__.pyi +++ b/python/quicknode_sdk/_core/__init__.pyi @@ -234,6 +234,7 @@ __all__ = [ "SolanaWalletFilterByListTemplate", "SolanaWalletFilterTemplate", "SqlApiClient", + "SqlCluster", "SqlConfig", "StellarWalletTransactionsFilterArgs", "StellarWalletTransactionsFilterByListArgs", @@ -1837,7 +1838,7 @@ class CachedToken: A minted session JWT plus the endpoint it authenticates against and its wall-clock expiry. This is the unit cached by the RPC client and the unit a host persists between processes (e.g. the CLI's on-disk token cache). - + `exp_unix` is the JWT `exp` claim (unix seconds), used directly so it survives a process restart (unlike a monotonic `Instant`). """ @@ -5793,7 +5794,7 @@ class HttpConfig: def headers(self) -> typing.Optional[builtins.dict[builtins.str, builtins.str]]: r""" Custom HTTP headers added to every outbound request. - + **These headers OVERRIDE any SDK-managed header with the same name**, including `User-Agent`, `x-api-key`, `Accept`, and `Content-Type`. Header names are matched case-insensitively. Use this to override the @@ -5803,7 +5804,7 @@ class HttpConfig: def headers(self, value: typing.Optional[builtins.dict[builtins.str, builtins.str]]) -> None: r""" Custom HTTP headers added to every outbound request. - + **These headers OVERRIDE any SDK-managed header with the same name**, including `User-Agent`, `x-api-key`, `Accept`, and `Content-Type`. Header names are matched case-insensitively. Use this to override the @@ -7158,7 +7159,7 @@ class PaymentConfig: boundary. The private `key` field stays readable to the caller, but the SDK's own `Debug` redacts it (below) so an SDK log line or panic can't leak it. - + **Do not log your own `PaymentConfig`** — `println!("{config:?}")` on the derived-Debug *binding* object (napi/pyclass/hash) still shows the raw key. Only the SDK's internal rendering is redacted. @@ -7665,7 +7666,7 @@ class RpcApiClient: and defaults to `[]`. `network` selects a chain on the multichain endpoint (a key in the seeded network map, e.g. `"solana-mainnet"`); omit for the endpoint's default network. - + `endpoint_url` sends this call to a custom HTTP URL instead, bypassing the Tooling Access endpoint and the session JWT (no Authorization header is attached). It overrides the client-wide `RpcConfig.endpoint_url` @@ -7724,8 +7725,8 @@ class RpcApiClient: def gateway_drip(self, session: typing.Any) -> typing.Coroutine[typing.Any, typing.Any, typing.Any]: r""" Requests testnet tokens from the x402 faucet. Returns the funding - transaction as a dict `{account_id, transaction_hash}` — NOT a balance; - call `gateway_credits` afterwards for that. Allowed once per account. + transfer metadata as a dict. Circle-backed responses contain + `transfer_id`; direct transfers contain `transaction_hash`. """ def gateway_drawdown_call(self, method: builtins.str, session: typing.Any, network: builtins.str, params: typing.Optional[typing.Any] = None) -> typing.Coroutine[typing.Any, typing.Any, typing.Any]: r""" @@ -7739,7 +7740,7 @@ class RpcApiClient: decimal string) into the escrow. Returns the channel state dict — persist it; the gateway has no read-only channel endpoint, so a lost record means opening a new channel. Moves real funds; single-attempt. - + Takes no network: the channel is scoped by the configured pay network and asset, so one channel funds calls to every supported network. """ @@ -7758,7 +7759,7 @@ class RpcApiClient: r""" Fetches the gateway's view of the channel as a dict `{channel_id, accepted_cumulative, spent}` (amounts are decimal strings). - + **This costs one request unit** and advances the voucher by `per_call`, exactly like a session call — persist the advanced `cumulative_spent`. Raises `PaymentUnsupportedError` before any network I/O when the channel @@ -8283,6 +8284,10 @@ class SolanaWalletFilterTemplate: @typing.final class SqlApiClient: + def list_clusters(self) -> typing.Coroutine[typing.Any, typing.Any, list[SqlCluster]]: + r""" + Lists the clusters available to query. + """ def query(self, query: builtins.str, cluster_id: builtins.str) -> typing.Coroutine[typing.Any, typing.Any, QueryResponse]: r""" Executes a SQL query against the given cluster and returns the result @@ -8294,6 +8299,35 @@ class SqlApiClient: columns, types, sort keys, and partition strategies. """ +@typing.final +class SqlCluster: + r""" + A cluster that SQL queries can target, as returned by `list_clusters`. + """ + @property + def id(self) -> builtins.str: + r""" + Cluster identifier (e.g. `"hyperliquid-core-mainnet"`); pass it as + `cluster_id` to `query` and `get_schema`. + """ + @id.setter + def id(self, value: builtins.str) -> None: + r""" + Cluster identifier (e.g. `"hyperliquid-core-mainnet"`); pass it as + `cluster_id` to `query` and `get_schema`. + """ + @property + def display_name(self) -> builtins.str: + r""" + Human-readable name (e.g. `"Hyperliquid (HyperCore)"`). + """ + @display_name.setter + def display_name(self, value: builtins.str) -> None: + r""" + Human-readable name (e.g. `"Hyperliquid (HyperCore)"`). + """ + def __new__(cls, id: builtins.str, display_name: builtins.str) -> SqlCluster: ... + @typing.final class SqlConfig: @property diff --git a/python/quicknode_sdk/init_manual_override.pyi b/python/quicknode_sdk/init_manual_override.pyi index b1e7b8b..244639a 100644 --- a/python/quicknode_sdk/init_manual_override.pyi +++ b/python/quicknode_sdk/init_manual_override.pyi @@ -223,6 +223,7 @@ from quicknode_sdk._core import ( GetListResponse, ListContainsItemResponse, SqlApiClient, + SqlCluster, QueryResponse, ColumnMeta, QueryStatistics, @@ -550,6 +551,7 @@ __all__ = [ "GetListResponse", "ListContainsItemResponse", "SqlApiClient", + "SqlCluster", "QueryResponse", "ColumnMeta", "QueryStatistics", diff --git a/ruby/sig/quicknode_sdk.rbs b/ruby/sig/quicknode_sdk.rbs index 8d610a8..cd20a36 100644 --- a/ruby/sig/quicknode_sdk.rbs +++ b/ruby/sig/quicknode_sdk.rbs @@ -242,6 +242,7 @@ module QuicknodeSdk class Sql def initialize: (untyped native) -> void + def list_clusters: () -> untyped def query: (query: String, cluster_id: String) -> untyped def get_schema: (cluster_id: String) -> untyped end From 715183f6925f81618d08af642b7c87a840ab57ba Mon Sep 17 00:00:00 2001 From: John Mitsch Date: Fri, 13 Nov 2026 09:46:54 -0500 Subject: [PATCH 3/4] docs(sql): document list_clusters and add it to the SQL examples The four SQL example scripts now list clusters first and assert that each entry has an id and a display name. --- crates/core/README.md | 16 +++++++++++++++- crates/core/examples/sql.rs | 18 ++++++++++++++++++ npm/README.md | 16 +++++++++++++++- npm/examples/sql.ts | 10 ++++++++++ python/README.md | 16 +++++++++++++++- python/examples/sql.py | 6 ++++++ ruby/README.md | 16 +++++++++++++++- ruby/examples/sql.rb | 6 ++++++ 8 files changed, 100 insertions(+), 4 deletions(-) diff --git a/crates/core/README.md b/crates/core/README.md index dbfd6c4..f60f766 100644 --- a/crates/core/README.md +++ b/crates/core/README.md @@ -1998,7 +1998,21 @@ qn.kvstore.delete_list("my-list").await?; ### SQL Client -Accessed as `qn.sql`. Runs SQL queries against indexed blockchain data and fetches the database schema. Backed by `https://api.quicknode.com/sql/rest/v1/`. +Accessed as `qn.sql`. Lists the available clusters, runs SQL queries against indexed blockchain data, and fetches the database schema. Backed by `https://api.quicknode.com/sql/rest/v1/`. + +##### `list_clusters` + +Lists the clusters available to query. Pass a cluster's `id` as the `cluster_id` for `query` and `get_schema`. The request does not need an API key, and the SDK does not send one. + +**Parameters**: none. + +**Returns**: `Vec`, each with `id` and `display_name`. + +```rust +// Rust +let clusters = qn.sql.list_clusters().await?; +println!("{:?}", clusters.iter().map(|c| &c.id).collect::>()); +``` ##### `query` diff --git a/crates/core/examples/sql.rs b/crates/core/examples/sql.rs index ff6cf3b..07323d3 100644 --- a/crates/core/examples/sql.rs +++ b/crates/core/examples/sql.rs @@ -8,6 +8,24 @@ async fn main() { let config = SdkFullConfig::from_env().expect("Config from env failed"); let qn = QuicknodeSdk::new(&config).expect("sdk failed to initialize"); + // ── Clusters ────────────────────────────────────────────────────────────── + + let clusters = qn.sql.list_clusters().await.expect("list_clusters failed"); + println!( + "clusters: {:?}", + clusters.iter().map(|c| &c.id).collect::>() + ); + assert!( + clusters + .iter() + .all(|c| !c.id.is_empty() && !c.display_name.is_empty()), + "every cluster has an id and a display name" + ); + assert!( + clusters.iter().any(|c| c.id == CLUSTER_ID), + "{CLUSTER_ID} is in the cluster list" + ); + // ── Query ───────────────────────────────────────────────────────────────── let params = QueryParams { diff --git a/npm/README.md b/npm/README.md index b529298..3d1e9db 100644 --- a/npm/README.md +++ b/npm/README.md @@ -1839,7 +1839,21 @@ await qn.kvstore.deleteList("my-list"); ### SQL Client -Accessed as `qn.sql`. Runs SQL queries against indexed blockchain data and fetches the database schema. Backed by `https://api.quicknode.com/sql/rest/v1/`. +Accessed as `qn.sql`. Lists the available clusters, runs SQL queries against indexed blockchain data, and fetches the database schema. Backed by `https://api.quicknode.com/sql/rest/v1/`. + +##### `list_clusters` / `listClusters` + +Lists the clusters available to query. Pass a cluster's `id` as the `cluster_id` / `clusterId` for `query` and `getSchema`. The request does not need an API key, and the SDK does not send one. + +**Parameters**: none. + +**Returns**: an array of `SqlCluster`, each with `id` and `display_name` / `displayName`. + +```typescript +// Node.js +const clusters = await qn.sql.listClusters(); +console.log(clusters.map((c) => c.id)); +``` ##### `query` diff --git a/npm/examples/sql.ts b/npm/examples/sql.ts index a72b169..faa3efd 100644 --- a/npm/examples/sql.ts +++ b/npm/examples/sql.ts @@ -5,6 +5,16 @@ const CLUSTER_ID = "hyperliquid-core-mainnet"; async function main() { const qn = QuicknodeSdk.fromEnv(); + // Clusters + const clusters = await qn.sql.listClusters(); + console.log(`clusters: ${clusters.map((c) => c.id).join(", ")}`); + if (!clusters.every((c) => c.id && c.displayName)) { + throw new Error("every cluster must have an id and a displayName"); + } + if (!clusters.some((c) => c.id === CLUSTER_ID)) { + throw new Error(`${CLUSTER_ID} not in cluster list`); + } + // Query const resp = await qn.sql.query( "SELECT toDateTime(block_time) AS time, action_type, user " + diff --git a/python/README.md b/python/README.md index 54b2b5a..620f684 100644 --- a/python/README.md +++ b/python/README.md @@ -1834,7 +1834,21 @@ await qn.kvstore.delete_list("my-list") ### SQL Client -Accessed as `qn.sql`. Runs SQL queries against indexed blockchain data and fetches the database schema. Backed by `https://api.quicknode.com/sql/rest/v1/`. +Accessed as `qn.sql`. Lists the available clusters, runs SQL queries against indexed blockchain data, and fetches the database schema. Backed by `https://api.quicknode.com/sql/rest/v1/`. + +##### `list_clusters` + +Lists the clusters available to query. Pass a cluster's `id` as the `cluster_id` for `query` and `get_schema`. The request does not need an API key, and the SDK does not send one. + +**Parameters**: none. + +**Returns**: `list[SqlCluster]`, each with `id` and `display_name`. + +```python +# Python +clusters = await qn.sql.list_clusters() +print([c.id for c in clusters]) +``` ##### `query` diff --git a/python/examples/sql.py b/python/examples/sql.py index 28f0e3c..7e636c1 100644 --- a/python/examples/sql.py +++ b/python/examples/sql.py @@ -7,6 +7,12 @@ async def main(): qn = QuicknodeSdk.from_env() + # Clusters + clusters = await qn.sql.list_clusters() + print(f"clusters: {[c.id for c in clusters]}") + assert all(c.id and c.display_name for c in clusters) + assert any(c.id == CLUSTER_ID for c in clusters), f"{CLUSTER_ID} not in cluster list" + # Query resp = await qn.sql.query( query=( diff --git a/ruby/README.md b/ruby/README.md index 4e32ff4..ef7b100 100644 --- a/ruby/README.md +++ b/ruby/README.md @@ -1847,7 +1847,21 @@ qn.kvstore.delete_list(key: "my-list") ### SQL Client -Accessed as `qn.sql`. Runs SQL queries against indexed blockchain data and fetches the database schema. Backed by `https://api.quicknode.com/sql/rest/v1/`. +Accessed as `qn.sql`. Lists the available clusters, runs SQL queries against indexed blockchain data, and fetches the database schema. Backed by `https://api.quicknode.com/sql/rest/v1/`. + +##### `list_clusters` + +Lists the clusters available to query. Pass a cluster's `id` as the `cluster_id:` for `query` and `get_schema`. The request does not need an API key, and the SDK does not send one. + +**Parameters**: none. + +**Returns** an Array of Hashes, each with `id` and `display_name`. + +```ruby +# Ruby +clusters = qn.sql.list_clusters +puts clusters.map { |c| c[:id] } +``` ##### `query` diff --git a/ruby/examples/sql.rb b/ruby/examples/sql.rb index dd97a26..5911185 100644 --- a/ruby/examples/sql.rb +++ b/ruby/examples/sql.rb @@ -4,6 +4,12 @@ qn = QuicknodeSdk::SDK.from_env +# Clusters +clusters = qn.sql.list_clusters +puts "clusters: #{clusters.map { |c| c[:id] }.join(', ')}" +raise "every cluster must have an id and a display_name" unless clusters.all? { |c| c[:id] && c[:display_name] } +raise "#{CLUSTER_ID} not in cluster list" unless clusters.any? { |c| c[:id] == CLUSTER_ID } + # Query resp = qn.sql.query( query: "SELECT toDateTime(block_time) AS time, action_type, user " \ From 04f216856b901c3716007966864fa2f0e07ce97a Mon Sep 17 00:00:00 2001 From: John Mitsch Date: Fri, 13 Nov 2026 10:15:32 -0500 Subject: [PATCH 4/4] fix(sql): send the API key with list_clusters The clusters endpoint returns 401 when the x-api-key header is missing, so the request now uses the same keyed client as query and get_schema. --- crates/core/README.md | 2 +- crates/core/src/sql/mod.rs | 11 +++-------- npm/README.md | 2 +- python/README.md | 2 +- ruby/README.md | 2 +- 5 files changed, 7 insertions(+), 12 deletions(-) diff --git a/crates/core/README.md b/crates/core/README.md index f60f766..91c9ed4 100644 --- a/crates/core/README.md +++ b/crates/core/README.md @@ -2002,7 +2002,7 @@ Accessed as `qn.sql`. Lists the available clusters, runs SQL queries against ind ##### `list_clusters` -Lists the clusters available to query. Pass a cluster's `id` as the `cluster_id` for `query` and `get_schema`. The request does not need an API key, and the SDK does not send one. +Lists the clusters available to query. Pass a cluster's `id` as the `cluster_id` for `query` and `get_schema`. **Parameters**: none. diff --git a/crates/core/src/sql/mod.rs b/crates/core/src/sql/mod.rs index 4ad6351..812f34a 100644 --- a/crates/core/src/sql/mod.rs +++ b/crates/core/src/sql/mod.rs @@ -271,14 +271,11 @@ impl SqlApiClient { } /// Lists the clusters available to query. - // The cluster catalog is public, so this uses the keyless client: the - // account `x-api-key` is never sent, and an SDK built without an API key - // can still call it. pub async fn list_clusters(&self) -> Result, SdkError> { let url = self.config.sql().base_url.join("clusters")?; let resp = self .config - .rpc_http_client() + .http_client() .get(url) .send() .await @@ -342,7 +339,7 @@ impl SqlApiClient { mod tests { use super::*; use crate::{QuicknodeSdk, SdkFullConfig, SqlConfig}; - use wiremock::matchers::{body_json, method, path}; + use wiremock::matchers::{body_json, header, method, path}; use wiremock::{Mock, MockServer, ResponseTemplate}; fn make_sdk(base_url: String) -> QuicknodeSdk { @@ -375,9 +372,7 @@ mod tests { let server = MockServer::start().await; Mock::given(method("GET")) .and(path("/clusters")) - // The SDK under test has an API key; the public catalog request - // must not carry it. - .and(|req: &wiremock::Request| !req.headers.contains_key("x-api-key")) + .and(header("x-api-key", "test-key")) .respond_with(ResponseTemplate::new(200).set_body_json(serde_json::json!([ {"id": "hyperliquid-core-mainnet", "display_name": "Hyperliquid (HyperCore)"}, {"id": "solana-mainnet", "display_name": "Solana"} diff --git a/npm/README.md b/npm/README.md index 3d1e9db..eec33f2 100644 --- a/npm/README.md +++ b/npm/README.md @@ -1843,7 +1843,7 @@ Accessed as `qn.sql`. Lists the available clusters, runs SQL queries against ind ##### `list_clusters` / `listClusters` -Lists the clusters available to query. Pass a cluster's `id` as the `cluster_id` / `clusterId` for `query` and `getSchema`. The request does not need an API key, and the SDK does not send one. +Lists the clusters available to query. Pass a cluster's `id` as the `cluster_id` / `clusterId` for `query` and `getSchema`. **Parameters**: none. diff --git a/python/README.md b/python/README.md index 620f684..76cb16e 100644 --- a/python/README.md +++ b/python/README.md @@ -1838,7 +1838,7 @@ Accessed as `qn.sql`. Lists the available clusters, runs SQL queries against ind ##### `list_clusters` -Lists the clusters available to query. Pass a cluster's `id` as the `cluster_id` for `query` and `get_schema`. The request does not need an API key, and the SDK does not send one. +Lists the clusters available to query. Pass a cluster's `id` as the `cluster_id` for `query` and `get_schema`. **Parameters**: none. diff --git a/ruby/README.md b/ruby/README.md index ef7b100..54545fb 100644 --- a/ruby/README.md +++ b/ruby/README.md @@ -1851,7 +1851,7 @@ Accessed as `qn.sql`. Lists the available clusters, runs SQL queries against ind ##### `list_clusters` -Lists the clusters available to query. Pass a cluster's `id` as the `cluster_id:` for `query` and `get_schema`. The request does not need an API key, and the SDK does not send one. +Lists the clusters available to query. Pass a cluster's `id` as the `cluster_id:` for `query` and `get_schema`. **Parameters**: none.