QuickNode CI Contract Lane

Overview

Keep pull-request tests deterministic and credential-free. Run a minimal live QuickNode read only after trust has been established, with environment protection and no secrets exposed to forked code.

Prerequisites

• Existing test framework and CI provider
• QuickNode adapter boundary with injectable transport
• Protected environment containing a read-only endpoint or API key

Instructions

Step 1: Inventory the pipeline

Use Read and Grep to find workflow triggers, fork behavior, secret references, generated code, endpoint fixtures, and commands that can sign or submit transactions.

Step 2: Define offline contracts

Use Write or Edit to test JSON-RPC request IDs, chain-ID validation, result-versus-error parsing, timeout behavior, rate-limit classification, and redaction with fixtures. Mock at the transport boundary.

Step 3: Add a protected live read

Permit one documented, low-cost read method in a trusted environment. Assert chain identity and response shape rather than a volatile block value. Never load a funded signer or production write credential.

Step 4: Close the fork boundary

Do not expose QuickNode secrets to untrusted pull requests or execute fork-controlled code in a privileged pull_request_target context. Require environment approval or a trusted post-merge lane.

Step 5: Pin toolchain inputs

Use Bash(npm:*) to run the existing pinned test command. Commit lockfile changes with SDK upgrades, pin third-party workflow actions by immutable revision under repository policy, and reject install scripts not already reviewed.

Step 6: Produce a gate receipt

Record exact commit, command, offline results, live method, chain ID, latency, and redaction check. Make the live lane fail closed when its credential is expected but absent.

Tool Discipline

Use Read and Grep for CI discovery, Write/Edit for fixtures and workflow changes, and Bash(npm:*) only for repository-defined package and test commands. Do not invoke live RPC from an untrusted event.

Output

• Credential-free default contract suite
• Protected read-only integration lane
• Fork and secret-exposure controls
• Exact-head CI receipt

Examples

A public fork runs parser and retry fixtures only. A protected main-branch job reads eth_chainId, verifies the expected network, and stores no endpoint URL in logs.

Error Handling

QuickNode Error Triage

Overview

Preserve HTTP status, JSON-RPC code, chain error, method, network, and request identifier as separate facts. Do not treat every -32000 family response as retryable or overwrite a contract revert with a provider diagnosis.

Prerequisites

• A redacted failing request and response
• Endpoint ID, chain, network, protocol, and client version
• The expected method contract and a nearby successful request if available

Instructions

Step 1: Capture the first failure

Use Read and Grep to locate the earliest complete failure before wrapper retries transform it. Redact endpoint tokens, API keys, signed transactions, addresses when sensitive, and request bodies not needed for diagnosis.

Step 2: Assign the layer

Classify DNS/TLS/timeout, HTTP authentication, QuickNode infrastructure, endpoint security, chain-node, smart-contract, or client-decoding failure. Keep nested causes intact.

Step 3: Interpret QuickNode codes

Recognize -32007 per-second limit, -32008 per-minute limit, -32011 method limit, -32604 empty or unsupported method, and -32611 endpoint security-filter rejection. Verify other codes against the chain-specific reference.

Step 4: Inspect control-plane evidence

Use Bash(qn:*) for authenticated endpoint, metrics, or permitted error-log reads. Admin API endpoint logs are plan-gated; absence of access is not proof that no request reached QuickNode.

Step 5: Run one discriminating test

Compare a supported read method on the same endpoint, the same method with corrected parameters, or the same request in a non-production environment. Avoid retries that could resubmit a signed transaction.

Step 6: Route ownership

Assign the finding to credential owner, endpoint-security owner, capacity owner, chain integration, contract developer, or QuickNode support. Include only sanitized evidence and a reversible next action.

Tool Discipline

Use Read and Grep for local evidence and Bash(qn:*) only for read-only account inspection. This diagnostic workflow does not edit code, rotate credentials, change limits, or replay writes.

Output

• Layered failure classification
• Preserved HTTP, RPC, and chain facts
• One discriminating test result
• Named owner and safe next action

Examples

HTTP succeeds but JSON-RPC returns -32611; a simple allowed method works. Route the issue to endpoint filter configuration instead of increasing capacity or retrying.

Error Handling

QuickNode EVM Transaction Safety

Overview

Build a write path that treats signing, submission, and confirmation as separate state transitions. QuickNode transports the signed transaction; the application remains responsible for intent, signer custody, nonce coordination, chain identity, and reorganization policy.

Prerequisites

• A verified QuickNode endpoint and expected EVM chain ID
• A testnet signer held outside source code
• Contract ABI, write intent, value ceiling, and confirmation policy

Instructions

Step 1: Inspect the existing path

Use Read and Grep to find signers, private-key variables, nonce overrides, fee logic, retries, and receipt assumptions. Stop if secrets or signed raw transactions are logged.

Step 2: Define transaction intent

Use Write or Edit to express destination, calldata, value, chain ID, and caller policy as validated inputs. Reject unexpected networks and unbounded value before reaching the signer.

Step 3: Simulate and estimate

Run the equivalent read call and gas estimate at an explicit block tag when supported. Treat a revert as an application or chain-state result, not a transient provider failure.

Step 4: Coordinate nonce and fees

Assign one nonce owner per signer. Read pending nonce state, define replacement rules, and use chain-appropriate fee fields. Do not blindly overwrite a nonce or double fees on each timeout.

Step 5: Sign and broadcast once

Keep signing in a wallet, HSM, or approved remote signer. Persist the signed transaction hash before submission. On an ambiguous timeout, query by hash before broadcasting again.

Step 6: Confirm by policy

Track inclusion, receipt status, block hash, and the required chain-specific confirmation depth. Reconcile dropped or reorganized receipts and expose a durable business-operation idempotency key.

Tool Discipline

Use Read and Grep for transaction-path discovery and Write/Edit for validation, state-machine, and tests. This skill never asks the agent to hold a private key or execute a funded transaction.

Output

• Validated transaction-intent schema
• Signer, nonce, fee, and broadcast ownership contract
• Ambiguous-submission reconciliation path
• Chain-specific confirmation and reorg policy

Examples

A payment request is recorded before signing. If broadcast times out, the worker searches for the known transaction hash and never manufactures a second payment from the same business request.

Error Handling

QuickNode Chain-Data Contract

Overview

Select an endpoint from required data semantics, not from a generic “Web3 RPC” label. Current state, historical block data, historical state, traces, token/NFT indexes, REST, gRPC, and WebSocket subscriptions have different availability and retention.

Prerequisites

• Chain, network, and protocol requirements
• Oldest required block, state, or epoch
• Required methods, consistency, pagination, latency, and recovery behavior

Authentication

Use an endpoint token for data-plane RPC, passed through the documented endpoint URL or x-token header. Use a separate account API key in x-api-key only for Admin API capability inspection. Never place either credential in the written data contract or its tests.

Instructions

Step 1: Inventory queries

Use Read and Grep to extract every RPC, REST, gRPC, subscription, and add-on method. Record block tags, pagination assumptions, expected response shapes, and historical lookback.

Step 2: Classify historical semantics

Distinguish historical block retrieval from historical state queries. Determine whether the chain exposes archive mode, a pruning window, or a specialized endpoint path. Never infer “archive” from an Ethereum-centric example.

Step 3: Verify the chain reference

Consult the current QuickNode API overview for the exact chain and network. Confirm supported APIs, protocols, chain ID, archive status, pruning policy, and product availability.

Step 4: Separate standard and enhanced APIs

Identify standard chain methods versus QuickNode add-ons or indexed Token/NFT APIs. Record entitlement and method contract explicitly; a qn_* name does not guarantee it is enabled on every endpoint.

Step 5: Design bounded reads

Use Write or Edit to add pagination, maximum range, explicit block tags, response-size controls, and checkpointing. Treat a missing next-page token or pruned-state response as a contract event.

Step 6: Prove representative history

Test current, boundary-age, and oldest-required records in a non-destructive acceptance suite. Pin expected chain identity and response invariants without snapshotting volatile tip values.

Tool Discipline

Use Read and Grep for query discovery and Write/Edit for the data contract and tests. This design skill does not enable add-ons, provision endpoints, or execute production queries.

Output

• Chain/network/API capability matrix
• Historical retention and archive decision
• Pagination and checkpoint contract
• Representative acceptance cases and plan dependencies

Examples

An analytics service needs historical contract state, not merely old block bodies. Its architecture selects an archive-capable network endpoint and tests a block older than …

QuickNode Credit and Cost Control

Overview

Optimize measured API credits, not a guessed requests-per-dollar formula. Account billing periods and endpoint rolling metrics answer different questions, and Streams, Webhooks, SQL, and endpoints can have different consumption models.

Prerequisites

• Billing window, plan, budget, and workload owner
• Access to Usage & Billing or authorized usage reads
• Product, endpoint, method, chain, and environment tags

Instructions

Step 1: Define the denominator

Use Read and Grep to identify workloads, schedules, duplicate callers, cache policy, backfills, and high-cardinality queries. State whether the decision concerns the billing cycle or a rolling performance window.

Step 2: Retrieve usage

Use Bash(qn:*) for authenticated usage and billing reads. Break consumption down by product and, where supported, endpoint, method, chain, or tag. Do not print invoices or account details into public logs.

Step 3: Attribute value

Map each large credit consumer to a product outcome and owner. Separate necessary live reads, historical backfills, retries, failed calls, polling, and abandoned experiments.

Step 4: Choose a safe lever

Use Write or Edit to cache immutable results, replace polling with an event product when justified, bound historical ranges, use pagination and selective fields, or schedule backfills. Never trade correctness for a lower request count silently.

Step 5: Model the change

Apply the account's current credit and pricing facts to measured volumes. Include plan limits, add-ons, flat-rate endpoints, and private terms only when verified; do not publish confidential pricing.

Step 6: Verify one billing interval

Compare expected and actual credits, errors, latency, freshness, and business completeness. Alert on both budget burn and missing work so a broken integration cannot look “cheap.”

Tool Discipline

Use Read and Grep for demand discovery, Bash(qn:*) for read-only account usage, and Write/Edit for controlled optimizations. Plan changes, endpoint pauses, and add-on changes require an owner checkpoint.

Output

• Credit attribution by product and owner
• Verified plan and billing assumptions
• One correctness-preserving optimization
• Forecast, acceptance metric, and rollback threshold

Examples

A nightly job repeatedly scans the same historical range. It persists a verified cursor and bounded overlap, reducing credits while retaining reorg reconciliation.

Error Handling

QuickNode Redacted Debug Bundle

Overview

Collect the smallest evidence set that can distinguish transport, QuickNode infrastructure, endpoint policy, chain, and client failures. Never archive a full endpoint URL, API key, endpoint token, private key, or signed raw transaction.

Prerequisites

• Endpoint ID, chain, network, method, and bounded UTC window
• Incident owner and approved evidence destination
• Redaction rules for addresses, calldata, and business payloads

Instructions

Step 1: Freeze scope

State the first and last relevant timestamps, affected deployment, client version, endpoint ID, network, and request class. Exclude unrelated logs and broad home-directory collection.

Step 2: Gather local evidence

Use Read and Grep for sanitized configuration shape, application error chain, retry count, timeout, request ID, and dependency versions. Replace endpoint URLs with a stable redacted label.

Step 3: Gather provider evidence

Use Bash(qn:*) for authenticated, read-only endpoint status, metrics, and permitted error logs. Detailed Admin API logs are plan-gated; record “not available” instead of widening access.

Step 4: Preserve protocol layers

Record DNS/TLS outcome, HTTP status, JSON-RPC id, error code and message, chain error, latency, and response size separately. Include one nearby successful method when safe.

Step 5: Reproduce minimally

Use a documented read method, timeout, and non-production or read-only context. Do not reproduce transaction submission, a contract write, or a historical scan with uncontrolled range.

Step 6: Run a leak review

Use Grep on the proposed bundle for quiknode.pro, token-like paths, x-token, x-api-key, private-key markers, authorization headers, and raw signed transactions. Refuse delivery until findings are removed.

Tool Discipline

Use Read and Grep for bounded local evidence and Bash(qn:*) for read-only provider facts. This skill does not write archives, upload files, alter endpoints, or call transaction methods.

Output

• Scope and UTC incident window
• Redacted layered request/response evidence
• Metrics and provider-status comparison
• Minimal reproduction and leak-review receipt

Examples

A bundle includes endpoint ID, eth_getLogs, a ten-minute window, p95 latency, HTTP 200 with JSON-RPC error, and a sanitized request ID. It excludes the endpoint hostname path and log-filter contents.

Error Handling

QuickNode Deployment Gate

Overview

Release configuration before traffic, prove the selected chain and product contracts, then increase exposure in stages. Keep old endpoints or tokens available through a bounded rollback window.

Prerequisites

• Release commit, target environment, endpoint and product inventory
• Secret-manager references for environment-specific credentials
• SLO, canary cohort, rollback owner, and maximum cutover window

Instructions

Step 1: Audit the release

Use Read and Grep to find endpoint variables, literal URLs, chain IDs, network names, SDK versions, write paths, Stream/Webhook destinations, and timeout/retry changes.

Step 2: Validate control-plane state

Use Bash(qn:*) for read-only endpoint, Stream, Webhook, security, usage, and metrics inspection. Confirm target resources exist and are active without changing status.

Step 3: Render safe configuration

Use Write or Edit to bind environment-specific secret references, expected chain identity, finite timeouts, bounded concurrency, and feature flags. Keep endpoint tokens out of artifacts and client bundles.

Step 4: Run preflight

Execute contract tests and one protected read-only request. For event products, use their test or preview path and confirm destination acknowledgement without creating business effects.

Step 5: Canary traffic

Shift a small declared cohort, then compare latency percentiles, error layers, chain identity, credit use, transaction landing or event completeness, and downstream queue health.

Step 6: Promote or roll back

Promote only when acceptance thresholds hold for the declared window. Roll back configuration and traffic before revoking the old credential; rotate compromised credentials immediately.

Tool Discipline

Use Read/Grep for release discovery, Write/Edit for reviewed configuration, and Bash(qn:*) for read-only control-plane evidence. Production mutation and traffic shifts require an explicit operator checkpoint.

Output

• Release and resource inventory
• Preflight and canary evidence
• Promotion thresholds and decision
• Tested rollback with credential-overlap deadline

Examples

A new endpoint receives five percent of read traffic. Chain ID, p95 latency, error rate, and credits remain within bounds before the service advances to the next stage.

Error Handling

QuickNode Read-Only Endpoint Proof

Overview

Establish transport, authentication, chain identity, response shape, and tip movement with raw JSON-RPC before adding an SDK. This keeps the first proof deterministic and prevents a client-library configuration error from looking like an endpoint outage.

Prerequisites

• A secret reference for the QuickNode endpoint and token
• The expected chain, network, protocol, and chain identifier
• A non-sensitive read method supported by that chain

Instructions

Step 1: Inspect the integration

Use Read and Grep to find the endpoint variable, expected chain ID, timeout, and current client wrapper. Stop if source or logs contain a literal QuickNode token.

Step 2: Define the probe

Use Write or Edit to create a small fixture containing only JSON-RPC version, a read method, empty parameters when valid, and a stable request ID. For EVM, pair eth_chainId with eth_blockNumber; do not submit a transaction.

Step 3: Call through the secret boundary

Use Bash(curl:*) with a timeout, JSON content type, and the endpoint injected by the runtime. Suppress verbose output because the URL may contain a token.

curl --silent --show-error --max-time 10 \
  --header 'content-type: application/json' \
  --data '{"jsonrpc":"2.0","method":"eth_chainId","params":[],"id":1}' \
  "$QUICKNODE_ENDPOINT"

Step 4: Validate semantics

Require HTTP success, matching JSON-RPC id, exactly one of result or error, and the expected chain ID. Parse hexadecimal block numbers explicitly rather than comparing their strings.

Step 5: Prove liveness

Read the latest block twice with a chain-appropriate interval. Tip movement is useful evidence but is not universal during quiet or halted networks, so compare against the chain status before declaring failure.

Step 6: Capture a safe receipt

Record timestamp, chain, network, method, latency, HTTP status, JSON-RPC error code if any, and redacted endpoint identity. Never retain the endpoint URL.

Tool Discipline

Use Read and Grep for configuration discovery, Write and Edit for a non-secret probe fixture, and Bash(curl:*) for bounded reads. Do not use this workflow for writes, signing, or funded keys.

Output

• Endpoint contract and expected chain identity
• Redacted transport and JSON-RPC receipt
• Liveness result with chain-status context
• Clear owner for any failed layer

Examples

An Ethereum mainnet endpoint returns chain ID 0x1 and a valid block number. A response from a testnet is rejected even though transport and authentication succeeded.

Error Handling

QuickNode Credential Boundary

Overview

Separate data-plane endpoint tokens from account-level API keys. An endpoint token authorizes chain RPC traffic; an API key authorizes QuickNode product and control-plane clients such as Admin API, Streams, the unified SDK, and qn.

Prerequisites

• The client, chain, network, environment, and required QuickNode products
• An approved secret manager and named rotation owner
• A QuickNode account role permitted to create only the required credential

Instructions

Step 1: Inventory credential consumers

Use Read and Grep to locate endpoint URLs, x-token, x-api-key, QN_SDK__API_KEY, and QUICKNODE_* references. Record owners without printing values. Treat any token embedded in an RPC URL as secret material.

Step 2: Select the credential type

Use an endpoint authentication token for HTTP or WSS chain RPC. Prefer the x-token header for server-side clients when the chain endpoint supports it. Use a dashboard API key for Admin API, SDK, Streams, Webhooks, KV Store, or SQL Explorer access.

Step 3: Separate environments

Give development, staging, production, and independent applications separate endpoint tokens. Multi-token authentication permits revoking one consumer without rotating every workload. Do not reuse a human CLI session as a production service identity.

Step 4: Configure clients safely

Use Write or Edit to add secret references and documented variable names, never values. Configure the unified SDK with QN_SDK__API_KEY. Use Bash(qn:*) for qn auth login and qn auth whoami only in an approved interactive operator session.

Step 5: Verify the intended boundary

Use Bash(curl:*) for one read-only JSON-RPC probe with the token supplied by the runtime secret mechanism. Confirm the chain identifier and an expected denial after removing the credential; never echo the endpoint URL or request headers.

Step 6: Record rotation

Document credential type, endpoint or API scope, consumers, storage reference, creation date, review date, and revoke-first rollback. Rotate with overlap: create, deploy, verify, then revoke the old token.

Tool Discipline

Use Read and Grep for discovery, Write and Edit for secret references, Bash(qn:) for authenticated CLI identity checks, and Bash(curl:) only for redacted read probes. Never place a live endpoint URL in source, logs, shell history, or support evidence.

Output

• Credential-to-client matrix
• Environment-separated secret references
• Negative and positive verification results
• Rotation and revocation record

Examples

A production RPC service receives a dedicated endpoint token through its secret manager. A deploymen…

QuickNode Deterministic Local Loop

Overview

Develop against an injectable transport by default. Local tests should model QuickNode protocol contracts without a live token, then use one explicit sandbox read to catch integration drift.

Prerequisites

• Existing QuickNode or JSON-RPC adapter
• Repository test runner and fixture convention
• Optional non-production, read-only credential in a local secret manager

Instructions

Step 1: Locate the boundary

Use Read and Grep to find direct endpoint calls, SDK constructors, global environment reads, retries, timers, and response parsing. Choose one adapter seam for injection.

Step 2: Define fixture contracts

Use Write or Edit to add success, HTTP error, JSON-RPC error, timeout, rate limit, malformed response, and pagination fixtures. Preserve request IDs and nested causes.

Step 3: Inject transport and time

Pass the transport, base URL, clock, and sleeper into the adapter. Use documented SDK base URL overrides only for a local stub or approved staging endpoint.

Step 4: Sanitize recordings

If a real response becomes a fixture, retain only necessary fields and replace endpoint URLs, tokens, API keys, addresses, and business payloads. Add a leak assertion to the fixture test.

Step 5: Run fast tests

Use Bash(npm:*) to run the repository's pinned unit and contract commands. Keep network disabled in the default lane and make accidental outbound access fail.

Step 6: Opt into one live read

Gate a sandbox read behind an explicit variable or command. Verify chain identity and shape, cap timeout and calls, and skip cleanly when the opt-in credential is absent locally.

Tool Discipline

Use Read/Grep for adapter discovery, Write/Edit for injection and fixtures, and Bash(npm:*) for repository-defined tests. Do not use production endpoints, funded signers, or live writes.

Output

• Injectable QuickNode transport boundary
• Sanitized deterministic fixtures
• Fast offline test command
• Explicit sandbox-read contract

Examples

An SDK adapter receives a stub base URL and fake clock. Retry tests advance virtual time, while a separate opt-in command performs one authenticated chain-ID read.

Error Handling

Resources

• …

QuickNode Performance Tuning

Overview

Optimize against a declared service-level objective and QuickNode's endpoint metrics. Separate provider latency from client queueing, chain execution, payload transfer, and downstream decoding.

Prerequisites

• Endpoint ID, chain, network, and latency/error SLO
• A representative method and payload workload
• Access to endpoint metrics or an application-side measurement source

Instructions

Step 1: Establish a baseline

Use Read and Grep to find timeouts, concurrency, connection pools, retries, batch settings, and method mix. Measure end-to-end and provider-call latency separately.

Step 2: Read provider metrics

Use Bash(qn:*) for authenticated endpoint metrics, including method calls, response codes, chain errors, and supported percentile views. Keep the time range and percentile explicit.

Step 3: Segment the workload

Compare method, network, payload size, block age, cacheability, and protocol. Historical traces and large log ranges must not be averaged with a small latest-block read.

Step 4: Remove avoidable work

Use Write or Edit to reuse connections and configured clients, coalesce identical reads, cache immutable block results, paginate large ranges, and request only necessary fields where the API supports it.

Step 5: Control concurrency

Set a bounded in-flight limit below measured saturation. Use JSON-RPC batching only where the chain and client contract support it, and cap both batch count and response size.

Step 6: Validate the change

Replay the same workload and compare p50, p95, p99, error rate, credits, and application queue time. Roll back if tail latency or chain-error rates worsen even when the mean improves.

Tool Discipline

Use Read and Grep for code and configuration discovery, Bash(qn:*) for read-only metrics, and Write/Edit for bounded performance changes and tests. Do not change production capacity or rate limits implicitly.

Output

• Layered baseline and SLO
• Method-segmented bottleneck finding
• One controlled optimization
• Before/after percentile, error, and credit receipt

Examples

A logs query dominates p99 and payload bytes. The service narrows block ranges and paginates that method while leaving fast latest-block reads unchanged.

Error Handling

Resour…

QuickNode Production Readiness

Overview

Review the actual runtime and QuickNode control plane against declared identity, security, capacity, data, correctness, observability, and recovery contracts. Return a decision with blockers, not a generic checklist score.

Prerequisites

• Release commit and deployment inventory
• Chain/network, data-retention, and product requirements
• SLOs, budget, incident owner, and rollback runbook

Instructions

Step 1: Verify identity and secrets

Use Read and Grep to confirm environment-specific secret references, expected chain IDs, no literal endpoint tokens, separate Admin API keys, and no funded signer in CI or logs.

Step 2: Verify provider controls

Use Bash(qn:*) for read-only inspection of endpoint status, tokens, filters, method/IP limits, tags, usage, metrics, and active or paused event products. Record unavailable plan-gated evidence.

Step 3: Verify data and write semantics

Confirm API family, method entitlement, archive/pruning boundary, pagination, block tags, transaction idempotency, nonce owner, confirmation depth, and reorg behavior.

Step 4: Verify reliability

Check finite timeouts, bounded concurrency, classified retries, circuit breaking, WebSocket recovery, Stream/Webhook idempotency, destination acknowledgement, and backlog monitoring.

Step 5: Verify observability and cost

Require endpoint and application latency, error layers, request IDs, chain errors, credit use, transaction landing, event completeness, and secret-safe logs.

Step 6: Exercise recovery

Run a read-only smoke test and tabletop credential rotation, endpoint cutover, provider degradation, event replay, and rollback. Name decision owners and expiry dates for any waiver.

Tool Discipline

Use Read and Grep for repository evidence and Bash(qn:*) for read-only provider evidence. This review does not deploy, change limits, revoke credentials, pause streams, or approve its own waivers.

Output

• PASS, CONDITIONAL, or BLOCKED decision
• Evidence per readiness dimension
• Owned blockers and expiring waivers
• Recovery and rollback receipt

Examples

A service is BLOCKED because it assumes archive state on a pruned chain and has no transaction-reconciliation path, even though its endpoint health and latency are green.

Error Handling

Resources

QuickNode Rate-Limit Control

Overview

Treat account-plan ceilings, IP limits, and operator-configured method limits as separate controls. QuickNode exposes distinct JSON-RPC errors for per-second, per-minute, and method limits; an HTTP status alone is not sufficient diagnosis.

Prerequisites

• Endpoint ID, plan, chain, network, and affected method
• A redacted error sample with HTTP and JSON-RPC fields
• Authorized dashboard, Admin API, or qn read access

Authentication

Authenticate qn interactively with qn auth login and verify the intended account with qn auth whoami. For direct Admin API inspection, inject a separate account API key as the x-api-key header. Endpoint tokens in URLs or x-token headers authenticate RPC traffic but do not replace control-plane credentials.

Instructions

Step 1: Classify the signal

Use Read and Grep to find the first complete redacted response. Preserve QuickNode codes such as -32007 per-second, -32008 per-minute, and -32011 method limit. Separate client timeouts and chain-node errors.

Step 2: Read the configured limits

Use Bash(qn:*) to inspect endpoint and method-rate settings through authenticated read commands. If the CLI version lacks the required view, use the dashboard or documented Admin API rather than guessing a number.

Step 3: Measure demand

Group requests by endpoint, token, source IP, method, and interval. Distinguish HTTP calls from WebSocket subscription creation; subscription responses do not count like new requests.

Step 4: Choose the control

Reduce concurrency, coalesce duplicate reads, cache immutable results, or set a method limit that protects expensive calls. Raising a plan limit is a capacity decision, not the first retry strategy.

Step 5: Implement bounded retry

Use Write or Edit to retry only idempotent reads and only recognized transient limit responses. Apply jitter, cap attempts and elapsed time, and honor a provider delay header when documented. Never automatically replay transaction submissions.

Step 6: Prove under load

Test below and above the intended threshold in a non-production endpoint. Confirm the expected code, bounded client behavior, recovery, and absence of synchronized retry bursts.

Tool Discipline

Use Read and Grep for error and demand discovery, Bash(qn:*) for authenticated read-only control-plane inspection, and Write/Edit for bounded retry or throttling code. Require explicit approval before changing production limits.

Output

• Limit-layer classification
• Measured method and interval demand
• Bounded client-control change
• Before/after load receipt and rollback threshold

Examples

A single trac…

QuickNode Production Reference Architecture

Overview

Separate provisioning and account governance from chain traffic, and separate synchronous reads/writes from asynchronous event ingestion. Give every credential, endpoint, cursor, queue, and recovery path one owner.

Prerequisites

• Service inventory and trust boundaries
• Chain/network, method, history, write, and event requirements
• SLO, recovery, compliance, and cost constraints

Instructions

Step 1: Map control and data planes

Use Read and Grep to identify Admin API, unified SDK, qn, RPC/WSS endpoints, Streams, Webhooks, SQL Explorer, and KV Store usage. Mark credentials and mutation authority.

Step 2: Isolate credentials

Use separate API keys for control-plane automation and endpoint tokens for data-plane RPC. Separate applications and environments with multiple tokens; keep signing keys outside QuickNode clients.

Step 3: Split synchronous workloads

Route bounded reads through chain-specific adapters. Put transaction intent, signing, broadcast identity, confirmation, and reorg reconciliation behind a dedicated write service.

Step 4: Build asynchronous ingestion

Terminate Streams or Webhooks at an authenticated receiver, acknowledge after durable enqueue, and process idempotently. Persist a replay cursor and send large historical pipelines to an appropriate durable destination.

Step 5: Define data capability

Use Write or Edit to record chain, network, API family, add-ons, archive/pruning semantics, pagination, and block consistency. Do not assume feature parity across chains.

Step 6: Close observability and recovery

Correlate application requests with endpoint metrics and sanitized request IDs. Define endpoint/token cutover, chain-provider degradation, event replay, transaction reconciliation, and budget alerts.

Tool Discipline

Use Read and Grep for topology discovery and Write/Edit for architecture records, interfaces, and tests. This design workflow performs no account, endpoint, Stream, or production mutation.

Output

• Trust-boundary and credential map
• Synchronous read/write interfaces
• Durable event-ingestion and replay path
• Observability, cost, and recovery contracts

Examples

An API serves cached finalized reads, a signer service owns transaction state, and a Stream receiver writes authenticated batches to a queue. Admin automation has no signer or endpoint token.

Error Handling

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 …

QuickNode Endpoint Hardening

Overview

Protect endpoint tokens as credentials, isolate consumers with multiple tokens, and layer only controls that match the client threat model. A browser referrer rule is not a substitute for keeping privileged RPC or account keys on a server.

Prerequisites

• Endpoint inventory with owners, applications, and environments
• Current plan and available endpoint-security controls
• A threat model covering browser, server, CI, and operator access

Instructions

Step 1: Find exposure

Use Read and Grep for quiknode.pro, x-token, x-api-key, JWT configuration, logs, examples, and client bundles. Stop and rotate any live credential committed to Git or shipped to an untrusted client.

Step 2: Separate identities

Create distinct endpoint tokens for applications and environments. Keep Admin API/SDK API keys separate from chain RPC tokens. Apply least-privilege team and account roles.

Step 3: Choose layered controls

Use token authentication for every endpoint. Add JWT for short-lived server authorization when supported, referrer allowlists for browser-origin reduction, and IP or method limits for known traffic patterns. Document plan dependencies.

Step 4: Keep privileged calls server-side

Use Write or Edit to route transaction submission, archive/debug methods, and account-control calls through a trusted backend. Do not embed endpoint or API tokens in public JavaScript.

Step 5: Inspect configuration

Use Bash(qn:*) to read endpoint security state with an approved authenticated operator identity. Compare actual tokens, filters, limits, domains, and team access to the declared policy without printing secret values.

Step 6: Exercise response

Prove that an unauthorized origin, token, method, or IP is rejected as designed. Revoke one test token and confirm other isolated consumers continue. Record recovery time and escalation owner.

Tool Discipline

Use Read and Grep for exposure discovery, Write/Edit for server-side boundaries and policy, and Bash(qn:*) for read-only security inspection. Credential creation, revocation, and production filter changes require an explicit checkpoint.

Output

• Endpoint threat model and credential map
• Actual-versus-declared security control comparison
• Negative authorization tests
• Rotation and incident-response procedure

Examples

A public dApp calls a backend that holds the endpoint token. Production and staging use separate tokens, and a method limit prevents the public route from invoking debug methods.

Error Handling

QuickNode Upgrade and Migration

Overview

Treat client, endpoint, token, chain API, and event-pipeline changes as contract migrations. Preserve a parallel read path or replay boundary until the target proves identity, correctness, capacity, and recovery.

Prerequisites

• Current and target SDK, endpoint, chain/network, and product inventory
• Compatibility tests and representative traffic
• Cutover owner, rollback window, and data-reconciliation plan

Authentication

Keep target credentials separate from the current path during the dual run. Endpoint tokens authenticate RPC through a protected URL or x-token header; Admin API inspection uses a distinct x-api-key, while qn uses its authenticated account session. Redact all three from matrices and receipts.

Instructions

Step 1: Build the change matrix

Use Read and Grep to find SDK imports, endpoint URLs, API methods, protocols, chain IDs, archive assumptions, tokens, Stream/Webhook IDs, cursors, and platform targets.

Step 2: Read current contracts

Verify the target SDK platform matrix, product API, chain deprecation, supported protocol, pruning policy, and method response. Do not derive compatibility from an unrelated chain quickstart.

Step 3: Prepare the target

Use Bash(npm:*) for a reviewed pinned SDK update and lockfile change. Use Write or Edit to adapt behind a stable interface, add dual-read comparisons, and preserve old configuration for rollback.

Step 4: Inspect provider resources

Use Bash(qn:*) for read-only current/target endpoint, security, usage, metrics, Stream, and Webhook state. Create or mutate resources only after an explicit operator checkpoint.

Step 5: Canary and reconcile

Compare chain identity, response semantics, latency, errors, credits, transaction status, and event completeness. For event migrations, start from an overlap block and deduplicate by durable event identity.

Step 6: Cut over and retire

Shift traffic gradually, retain the old endpoint/token through the rollback window, then revoke or archive only after evidence and owner approval. Record deprecation and consumer communication.

Tool Discipline

Use Read/Grep for inventory, Write/Edit for adapters and tests, Bash(npm:) for pinned package operations, and Bash(qn:) for read-only resource evidence. Destructive retirement remains approval-gated.

Output

• Current-to-target compatibility matrix
• Tested adapter and dual-run evidence
• Cutover and replay plan
• Rollback receipt and retirement approval

Examples

A service moves from a legacy Core wrapper to the unified SDK for control-plane calls while retaining its chain provider adapter. Dual reads prove equivalence before the old dependency is removed.

QuickNode Event Delivery Contract

Overview

Choose Webhooks for template-driven notifications or Streams for programmable, historical, and multi-destination pipelines. Both require authenticity, fast acknowledgement, idempotency, and explicit chain-reorganization behavior.

Prerequisites

• Product choice, chain, network, dataset, and start range
• An HTTPS receiver or approved durable destination
• A secret store, queue, and replay-aware event identity

Authentication

Authenticate event delivery with the generated HMAC security token and verify the signature over the unmodified request bytes before parsing. For Streams, add mTLS when its trust model is required. Keep endpoint tokens and Admin API keys out of receiver configuration because they authenticate different QuickNode surfaces.

Instructions

Step 1: Select Webhooks or Streams

Use Read and Grep to identify filtering, backfill, batching, destination, and reorg needs. Streams supports filter functions and destinations such as webhook, object storage, PostgreSQL, and Kafka; do not paste a Webhooks payload assumption into Streams.

Step 2: Define authenticity

Use the product's generated security token for HMAC verification. Compare signatures in constant time over the exact received bytes. For Streams, consider mTLS and a private-CA configuration where appropriate.

Step 3: Bound the receiver

Use Write or Edit to cap body size, decode gzip only when configured, validate content type, verify authenticity before parsing, enqueue durably, and return 2xx within the configured timeout.

Step 4: Create an idempotency identity

Derive a stable key from product metadata plus chain, block hash, transaction or log position, and destination. Persist receipt before acknowledging; do not deduplicate only by transaction hash when multiple logs are possible.

Step 5: Handle retries and pauses

Treat delivery as at-least-once at the receiver. Streams processes batches sequentially, retries according to configuration, and can pause after maximum failures. Multiple destinations can replay to ones that already succeeded.

Step 6: Reconcile reorganizations

Configure and test the product's reorg behavior. Make downstream state reversible or versioned and keep a cursor that can be replayed from a documented block.

Tool Discipline

Use Read and Grep for receiver discovery and Write/Edit for verification, queueing, idempotency, and tests. Do not create or mutate a production Stream/Webhook without an explicit checkpoint.

Output

• Product and destination decision
• Authenticated bounded receiver
• Durable idempotency and replay contract
• Retry, pause, reorg, and recovery runbook

Examples

A Stream receiver verifies HMAC over raw bytes, writes the batch and id…