---

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:

• saas
• quicknode
• sdk
• typescript
• architecture compatibility: 'Unified SDK supports documented native targets; Node.js package supports TypeScript, CommonJS, ES modules, and Bun'

---

QuickNode Unified SDK Pattern

Overview

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.

Prerequisites

• Required product clients and account role
• A secret reference for QN_SDK__API_KEY
• A deployment target supported by the SDK native binaries

Instructions

Step 1: Audit existing clients

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

Step 2: Confirm platform support

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.

Step 3: Install deliberately

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.

Step 4: Build one client boundary

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();

Step 5: Select explicit product clients

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.

Step 6: Test the boundary

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.

Tool Discipline

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.

Output

• Product-client ownership map
• One reusable configured SDK boundary
• Platform and version compatibility receipt
• Unit and protected integration tests

Examples

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.

Error Handling

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

Resources

• SDK evidence and source notes
• Unified SDK
• SDK quickstart