---

name: quicknode-reference-architecture description: 'Analyze and design a QuickNode production boundary that separates control-plane API keys, data-plane endpoint tokens, chain reads and writes, event ingestion, durable state, and observability. Use when multiple services or QuickNode products need clear ownership and failure isolation. Trigger with: "analyze QuickNode architecture", "design QuickNode infrastructure", "audit QuickNode trust boundaries".' allowed-tools: Read, Grep, Write, Edit version: 2.0.0 argument-hint: '[systems-and-chain-workloads]' model: inherit effort: high license: MIT author: Jeremy Longshore jeremy@intentsolutions.io tags:

• saas
• quicknode
• architecture
• blockchain
• governance compatibility: 'Product availability, destination counts, and endpoint capabilities depend on chain and plan'

---

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

Failure	Response
One key spans control and data planes	Split identity and rotate through overlap
Event receiver performs business work inline	Insert a durable queue before acknowledgement
Chain capability is assumed	Bind the interface to a verified chain/network contract
Provider timeout can duplicate a write	Persist broadcast identity and reconcile before retry

Resources

• Architecture evidence and source notes
• QuickNode APIs
• Streams destinations