quicknode-sdk-patternsAdopt the current unified QuickNode SDK with explicit product clients, timeouts, environment configuration, and platform checks. Use when coordinating Admin API, RPC, Streams, Webhooks, KV Store, or SQL Explorer from one service. Trigger with: "use the QuickNode SDK", "build a QuickNode client", "standardize QuickNode API access".
Independent GitHub snapshot · Automated classification · Original documentation governs
name: quicknode-sdk-patterns description: 'Adopt the current unified QuickNode SDK with explicit product clients, timeouts, environment configuration, and platform checks. Use when coordinating Admin API, RPC, Streams, Webhooks, KV Store, or SQL Explorer from one service. Trigger with: "use the QuickNode SDK", "build a QuickNode client", "standardize QuickNode API access".' allowed-tools: Read, Grep, Write, Edit, Bash(npm:*) version: 2.0.0 argument-hint: '[language-and-product-clients]' model: inherit effort: high license: MIT author: Jeremy Longshore jeremy@intentsolutions.io tags:
Use one configured QuicknodeSdk instance and its named product clients. Do not confuse this control-plane SDK with a chain-specific ethers or viem provider, and do not retain old Core-only examples as the architecture for new multi-product services.
QN_SDK__API_KEYUse Read and Grep to find @quicknode/sdk, Core, direct api.quicknode.com calls, timeouts, retries, and duplicate API-key configuration. Classify chain RPC providers separately from QuickNode product clients.
Check the current SDK platform matrix before installing. Browser and unsupported native targets require a server-side boundary or direct documented APIs; do not assume a package that installs on one developer machine will load in every runtime.
Use Bash(npm:*) to add a reviewed, pinned @quicknode/sdk version and capture the lockfile change. Do not use an unbounded latest version in production automation.
Use Write or Edit to construct QuicknodeSdk.fromEnv() once, inject it into application modules, and set a finite HTTP timeout. Keep base URL overrides limited to local tests or approved staging proxies.
import { QuicknodeSdk } from '@quicknode/sdk';
export const quicknode = QuicknodeSdk.fromEnv();
Route account resources through admin, Tooling Access RPC through rpc, data pipelines through streams, template subscriptions through webhooks, cursor state through kvstore, and indexed queries through sql. Keep chain-specific endpoint RPC behind its own adapter.
Mock the SDK at the adapter edge. Add one authorized read-only integration test in a protected environment, validate typed error handling, and reject logs containing API keys or full endpoint URLs.
Use Read and Grep for migration discovery, Bash(npm:*) only for package operations, and Write/Edit for the adapter and tests. Never execute destructive Admin, Stream, or Webhook methods without an explicit operator checkpoint.
A release auditor uses quicknode.admin for endpoint inventory and quicknode.streams for paused-stream checks. Application chain reads remain in a separate RPC adapter with a distinct endpoint token.
| Failure | Response |
|---|---|
| Native module fails to load | Recheck the published platform matrix and deployment target |
| SDK returns 401 | Verify QN_SDK__API_KEY and account role |
| Wrong product base URL | Remove accidental production override and retest |
Old Core API conflicts | Isolate legacy chain calls and migrate behind an adapter |