QuickNode Ci Integration

Overview

Implementation patterns for QuickNode ci integration using blockchain RPC endpoints and the QuickNode SDK.

Prerequisites

• Completed quicknode-install-auth setup

Instructions

Step 1: Connect to QuickNode

import { ethers } from 'ethers';
const provider = new ethers.JsonRpcProvider(process.env.QUICKNODE_ENDPOINT);
const block = await provider.getBlockNumber();
console.log(`Connected at block ${block}`);

Output

• QuickNode integration for ci integration

Error Handling

Resources

• QuickNode Docs
• Ethereum API

Next Steps

See related QuickNode skills for more workflows.

QuickNode Common Errors

Overview

Quick reference for the top blockchain RPC errors when using QuickNode endpoints with ethers.js or viem.

Prerequisites

• QuickNode endpoint configured
• ethers.js or viem installed

Instructions

Error 1: Nonce Too Low

Error: nonce has already been used (error={"code":-32000,"message":"nonce too low"})

Fix:

// Get the correct nonce before sending
const nonce = await provider.getTransactionCount(wallet.address, 'pending');
const tx = await wallet.sendTransaction({ ...txData, nonce });

Error 2: Insufficient Funds

Error: insufficient funds for intrinsic transaction cost

Fix:

const balance = await provider.getBalance(wallet.address);
const gasEstimate = await provider.estimateGas(txData);
const feeData = await provider.getFeeData();
const totalCost = gasEstimate * feeData.gasPrice! + txData.value;
if (balance < totalCost) {
  console.error(`Need ${ethers.formatEther(totalCost)} ETH, have ${ethers.formatEther(balance)}`);
}

Error 3: Gas Estimation Failed (Call Revert)

Error: execution reverted (reason="ERC20: transfer amount exceeds balance")

Fix: The contract function would revert. Check contract requirements:

try {
  const gas = await contract.transfer.estimateGas(to, amount);
} catch (err) {
  console.error('Revert reason:', err.reason);
  // Check: sufficient token balance, approvals, contract state
}

Error 4: Rate Limited (429)

Error: 429 Too Many Requests

Fix: Implement exponential backoff or upgrade plan:

async function retryRpc<T>(fn: () => Promise<T>, retries = 3): Promise<T> {
  for (let i = 0; i < retries; i++) {
    try { return await fn(); }
    catch (err: any) {
      if (err.code === 'SERVER_ERROR' && i < retries - 1) {
        await new Promise(r => setTimeout(r, 1000 * Math.pow(2, i)));
        continue;
      }
      throw err;
    }
  }
  throw new Error('Max retries');
}

Error 5: Method Not Found

Error: Method not found — qn_getTokenMetadataByContractAddress

Fix: This method requires an add-on. Enable it in QuickNode Dashboard > Endpoints > Add-ons.

Error 6: WebSocket Connection Dropped

Error: WebSocket connection closed unexpectedly

Fix:

const wsProvider = new ethers.WebSocketProvider(process.env.QUICKNODE_WSS);
wsProvider.webso…

QuickNode Core Workflow A

Overview

Build EVM transaction workflows: send ETH, interact with contracts, listen for events, and handle gas estimation.

Prerequisites

• Completed quicknode-hello-world
• A funded wallet (use testnet for development)

Instructions

Step 1: Send ETH Transaction

import { ethers } from 'ethers';

const provider = new ethers.JsonRpcProvider(process.env.QUICKNODE_ENDPOINT);
const wallet = new ethers.Wallet(process.env.PRIVATE_KEY!, provider);

const tx = await wallet.sendTransaction({
  to: '0xRecipientAddress',
  value: ethers.parseEther('0.01'),
});
console.log(`TX sent: ${tx.hash}`);
const receipt = await tx.wait();
console.log(`Confirmed in block ${receipt!.blockNumber}, gas used: ${receipt!.gasUsed}`);

Step 2: Call Contract Write Function

const contractAddress = '0xYourContract';
const abi = ['function transfer(address to, uint256 amount) returns (bool)'];
const contract = new ethers.Contract(contractAddress, abi, wallet);

const tx = await contract.transfer('0xRecipient', ethers.parseUnits('100', 18));
const receipt = await tx.wait();
console.log(`Transfer confirmed: ${receipt!.hash}`);

Step 3: Listen for Events (WebSocket)

const wsProvider = new ethers.WebSocketProvider(process.env.QUICKNODE_WSS);
const contract = new ethers.Contract(contractAddress, ['event Transfer(address indexed from, address indexed to, uint256 value)'], wsProvider);

contract.on('Transfer', (from, to, value, event) => {
  console.log(`Transfer: ${from} -> ${to}: ${ethers.formatUnits(value, 18)}`);
});

Step 4: Gas Estimation

const gasEstimate = await contract.transfer.estimateGas('0xRecipient', ethers.parseUnits('100', 18));
const feeData = await provider.getFeeData();
const totalCost = gasEstimate * (feeData.gasPrice || 0n);
console.log(`Estimated gas: ${gasEstimate}, cost: ${ethers.formatEther(totalCost)} ETH`);

Output

• ETH transfer with receipt confirmation
• Smart contract interaction
• Real-time event listening via WebSocket
• Gas estimation before transactions

Error Handling

Resource…

QuickNode Core Workflow B — NFT & Token APIs

Overview

Use QuickNode's NFT and Token APIs to fetch metadata, check balances, and track transfer history. These are QuickNode-specific add-on APIs beyond standard EVM RPC.

Prerequisites

• Completed quicknode-core-workflow-a
• Token and NFT add-ons enabled on your QuickNode endpoint

Instructions

Step 1: Get Token Balances (QuickNode SDK)

import { Core } from '@quicknode/sdk';

const core = new Core({ endpointUrl: process.env.QUICKNODE_ENDPOINT });

// Get all ERC-20 token balances for a wallet
const balances = await core.client.request({
  method: 'qn_getWalletTokenBalance',
  params: [{ wallet: '0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045' }],
});
for (const token of balances.result) {
  console.log(`${token.name} (${token.symbol}): ${token.quantity}`);
}

Step 2: Get NFT Metadata

const nfts = await core.client.request({
  method: 'qn_fetchNFTs',
  params: [{
    wallet: '0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045',
    contracts: ['0xBC4CA0EdA7647A8aB7C2061c2E118A18a936f13D'],  // BAYC
    page: 1,
    perPage: 10,
  }],
});
for (const nft of nfts.result.assets) {
  console.log(`${nft.name} — Token ID: ${nft.tokenId}`);
  console.log(`  Image: ${nft.imageUrl}`);
}

Step 3: Track ERC-20 Transfers

const transfers = await core.client.request({
  method: 'qn_getWalletTokenTransactions',
  params: [{
    address: '0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045',
    contract: '0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48',  // USDC
    page: 1,
    perPage: 10,
  }],
});
for (const tx of transfers.result.transfers) {
  console.log(`${tx.from} -> ${tx.to}: ${tx.value} at block ${tx.blockNumber}`);
}

Step 4: Standard ERC-20 Balance (No Add-on Required)

import { ethers } from 'ethers';

const provider = new ethers.JsonRpcProvider(process.env.QUICKNODE_ENDPOINT);
const erc20Abi = ['function balanceOf(address) view returns (uint256)', 'function decimals() view returns (uint8)', 'function symbol() view returns (string)'];
const token = new ethers.Contract('0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48', erc20Abi, provider);

const [balance, decimals, symbol] = await Promise.all([
  token.balanceOf('0xWalletAddress'),
  token.decimals(),
  token.symbol(),
]);
console.log(`${symbol} balance: ${ethers.formatUnits(balance, decimals)}`);

Output

• ERC-20 token balances for any wallet
• NFT metadata with images and attributes
• Transfer history for token tracking
• Direct contract reads for standard operations

Error Handling

QuickNode Cost Tuning

Overview

Implementation patterns for QuickNode cost tuning using blockchain RPC endpoints and the QuickNode SDK.

Prerequisites

• Completed quicknode-install-auth setup

Instructions

Step 1: Connect to QuickNode

import { ethers } from 'ethers';
const provider = new ethers.JsonRpcProvider(process.env.QUICKNODE_ENDPOINT);
const block = await provider.getBlockNumber();
console.log(`Connected at block ${block}`);

Output

• QuickNode integration for cost tuning

Error Handling

Resources

• QuickNode Docs
• Ethereum API

Next Steps

See related QuickNode skills for more workflows.

QuickNode Debug Bundle

Overview

Implementation patterns for QuickNode debug bundle using blockchain RPC endpoints and the QuickNode SDK.

Prerequisites

• Completed quicknode-install-auth setup

Instructions

Step 1: Connect to QuickNode

import { ethers } from 'ethers';
const provider = new ethers.JsonRpcProvider(process.env.QUICKNODE_ENDPOINT);
const block = await provider.getBlockNumber();
console.log(`Connected at block ${block}`);

Output

• QuickNode integration for debug bundle

Error Handling

Resources

• QuickNode Docs
• Ethereum API

Next Steps

See related QuickNode skills for more workflows.

QuickNode Deploy Integration

Overview

Implementation patterns for QuickNode deploy integration using blockchain RPC endpoints and the QuickNode SDK.

Prerequisites

• Completed quicknode-install-auth setup

Instructions

Step 1: Connect to QuickNode

import { ethers } from 'ethers';
const provider = new ethers.JsonRpcProvider(process.env.QUICKNODE_ENDPOINT);
const block = await provider.getBlockNumber();
console.log(`Connected at block ${block}`);

Output

• QuickNode integration for deploy integration

Error Handling

Resources

• QuickNode Docs
• Ethereum API

Next Steps

See related QuickNode skills for more workflows.

QuickNode Hello World

Overview

Make your first blockchain queries: get block number, check ETH balance, read a smart contract.

Prerequisites

• Completed quicknode-install-auth with endpoint URL

Instructions

Step 1: Get Block Number

import { ethers } from 'ethers';
const provider = new ethers.JsonRpcProvider(process.env.QUICKNODE_ENDPOINT);

const blockNumber = await provider.getBlockNumber();
console.log(`Current block: ${blockNumber}`);

Step 2: Check ETH Balance

const address = '0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045'; // vitalik.eth
const balance = await provider.getBalance(address);
console.log(`Balance: ${ethers.formatEther(balance)} ETH`);

Step 3: Read Smart Contract (ERC-20 Token)

const usdcAddress = '0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48';
const abi = ['function balanceOf(address) view returns (uint256)', 'function decimals() view returns (uint8)'];
const usdc = new ethers.Contract(usdcAddress, abi, provider);

const decimals = await usdc.decimals();
const balance = await usdc.balanceOf(address);
console.log(`USDC balance: ${ethers.formatUnits(balance, decimals)}`);

Step 4: Get Transaction Receipt

const txHash = '0xabc...'; // Any transaction hash
const receipt = await provider.getTransactionReceipt(txHash);
console.log(`Status: ${receipt?.status === 1 ? 'Success' : 'Failed'}`);
console.log(`Gas used: ${receipt?.gasUsed.toString()}`);

Output

• Block number retrieved
• ETH balance checked
• ERC-20 contract read
• Transaction receipt fetched

Error Handling

Resources

• QuickNode Ethereum API
• ethers.js Documentation

Next Steps

Build transaction workflows: quicknode-core-workflow-a

QuickNode Install Auth

Overview

Set up QuickNode blockchain RPC endpoints and install the QuickNode SDK or ethers.js for blockchain interactions.

Prerequisites

• QuickNode account at quicknode.com
• An endpoint created for your target chain (Ethereum, Solana, etc.)
• Node.js 18+

Instructions

Step 1: Create Endpoint

1. Go to quicknode.com > Dashboard > Create Endpoint
2. Select chain: Ethereum Mainnet (or testnet for development)
3. Copy the HTTP URL and WSS URL
   HTTP: https://xxx-yyy.quiknode.pro/TOKEN/
   WSS: wss://xxx-yyy.quiknode.pro/TOKEN/

Step 2: Install SDK

set -euo pipefail
npm install @quicknode/sdk viem
# Or with ethers.js
npm install ethers

Step 3: Configure Environment

# .env
QUICKNODE_ENDPOINT=https://xxx-yyy.quiknode.pro/YOUR_TOKEN/
QUICKNODE_WSS=wss://xxx-yyy.quiknode.pro/YOUR_TOKEN/

Step 4: Verify Connection (QuickNode SDK)

import { Core } from '@quicknode/sdk';

const core = new Core({ endpointUrl: process.env.QUICKNODE_ENDPOINT });
const blockNumber = await core.client.request({ method: 'eth_blockNumber' });
console.log(`Connected! Current block: ${parseInt(blockNumber, 16)}`);

Step 5: Verify Connection (ethers.js)

import { ethers } from 'ethers';

const provider = new ethers.JsonRpcProvider(process.env.QUICKNODE_ENDPOINT);
const block = await provider.getBlockNumber();
console.log(`Connected! Block: ${block}`);

Output

• QuickNode endpoint configured
• SDK installed and verified
• Successful RPC call confirming connectivity

Error Handling

Resources

• QuickNode SDK Getting Started
• Ethereum Quickstart

Next Steps

First blockchain query: quicknode-hello-world

QuickNode Local Dev Loop

Overview

Implementation patterns for QuickNode local dev loop using blockchain RPC endpoints and the QuickNode SDK.

Prerequisites

• Completed quicknode-install-auth setup

Instructions

Step 1: Connect to QuickNode

import { ethers } from 'ethers';
const provider = new ethers.JsonRpcProvider(process.env.QUICKNODE_ENDPOINT);
const block = await provider.getBlockNumber();
console.log(`Connected at block ${block}`);

Output

• QuickNode integration for local dev loop

Error Handling

Resources

• QuickNode Docs
• Ethereum API

Next Steps

See related QuickNode skills for more workflows.

QuickNode Performance Tuning

Overview

Implementation patterns for QuickNode performance tuning using blockchain RPC endpoints and the QuickNode SDK.

Prerequisites

• Completed quicknode-install-auth setup

Instructions

Step 1: Connect to QuickNode

import { ethers } from 'ethers';
const provider = new ethers.JsonRpcProvider(process.env.QUICKNODE_ENDPOINT);
const block = await provider.getBlockNumber();
console.log(`Connected at block ${block}`);

Output

• QuickNode integration for performance tuning

Error Handling

Resources

• QuickNode Docs
• Ethereum API

Next Steps

See related QuickNode skills for more workflows.

QuickNode Prod Checklist

Overview

Implementation patterns for QuickNode prod checklist using blockchain RPC endpoints and the QuickNode SDK.

Prerequisites

• Completed quicknode-install-auth setup

Instructions

Step 1: Connect to QuickNode

import { ethers } from 'ethers';
const provider = new ethers.JsonRpcProvider(process.env.QUICKNODE_ENDPOINT);
const block = await provider.getBlockNumber();
console.log(`Connected at block ${block}`);

Output

• QuickNode integration for prod checklist

Error Handling

Resources

• QuickNode Docs
• Ethereum API

Next Steps

See related QuickNode skills for more workflows.

QuickNode Rate Limits

Overview

Implementation patterns for QuickNode rate limits using blockchain RPC endpoints and the QuickNode SDK.

Prerequisites

• Completed quicknode-install-auth setup

Instructions

Step 1: Connect to QuickNode

import { ethers } from 'ethers';
const provider = new ethers.JsonRpcProvider(process.env.QUICKNODE_ENDPOINT);
const block = await provider.getBlockNumber();
console.log(`Connected at block ${block}`);

Output

• QuickNode integration for rate limits

Error Handling

Resources

• QuickNode Docs
• Ethereum API

Next Steps

See related QuickNode skills for more workflows.

QuickNode Reference Architecture

Overview

Implementation patterns for QuickNode reference architecture using blockchain RPC endpoints and the QuickNode SDK.

Prerequisites

• Completed quicknode-install-auth setup

Instructions

Step 1: Connect to QuickNode

import { ethers } from 'ethers';
const provider = new ethers.JsonRpcProvider(process.env.QUICKNODE_ENDPOINT);
const block = await provider.getBlockNumber();
console.log(`Connected at block ${block}`);

Output

• QuickNode integration for reference architecture

Error Handling

Resources

• QuickNode Docs
• Ethereum API

Next Steps

See related QuickNode skills for more workflows.

QuickNode SDK Patterns

Overview

Production-ready patterns for blockchain development with QuickNode: provider singletons, retry logic, batch RPC calls, and multi-chain support.

Prerequisites

• Completed quicknode-install-auth
• ethers.js or @quicknode/sdk installed

Instructions

Step 1: Provider Singleton

import { ethers } from 'ethers';

let _provider: ethers.JsonRpcProvider | null = null;

export function getProvider(): ethers.JsonRpcProvider {
  if (!_provider) {
    _provider = new ethers.JsonRpcProvider(process.env.QUICKNODE_ENDPOINT, undefined, {
      staticNetwork: true,  // Skip chainId lookup on every call
      batchMaxCount: 10,    // Enable batch RPC
    });
  }
  return _provider;
}

Step 2: Retry Wrapper with Backoff

async function withRetry<T>(fn: () => Promise<T>, maxRetries = 3): Promise<T> {
  for (let attempt = 0; attempt <= maxRetries; attempt++) {
    try {
      return await fn();
    } catch (err: any) {
      const isRetryable = err.code === 'SERVER_ERROR' || err.code === 'TIMEOUT' || err.status === 429;
      if (!isRetryable || attempt === maxRetries) throw err;
      const delay = Math.min(1000 * Math.pow(2, attempt), 10000);
      await new Promise(r => setTimeout(r, delay));
    }
  }
  throw new Error('Unreachable');
}

// Usage
const balance = await withRetry(() => getProvider().getBalance(address));

Step 3: Multi-Chain Client Factory

const ENDPOINTS: Record<string, string> = {
  ethereum: process.env.QUICKNODE_ETH_ENDPOINT!,
  polygon: process.env.QUICKNODE_POLYGON_ENDPOINT!,
  arbitrum: process.env.QUICKNODE_ARB_ENDPOINT!,
};

const providers = new Map<string, ethers.JsonRpcProvider>();

export function getChainProvider(chain: string): ethers.JsonRpcProvider {
  if (!providers.has(chain)) {
    const url = ENDPOINTS[chain];
    if (!url) throw new Error(`No endpoint for chain: ${chain}`);
    providers.set(chain, new ethers.JsonRpcProvider(url, undefined, { staticNetwork: true }));
  }
  return providers.get(chain)!;
}

Step 4: Batch RPC Calls

async function batchGetBalances(addresses: string[]): Promise<Map<string, bigint>> {
  const provider = getProvider();
  const results = new Map<string, bigint>();

  // ethers.js batches these automatically when batchMaxCount > 1
  const promises = addresses.map(async (addr) => {
    const balance = await provider.getBalance(addr);
    results.set(addr, balance);
  });

  await Promise.all(promises);
  return results;
}

Step 5: Contract Wrapper with Caching

import { LRUCache } from 'lru-cache';

const contra…

QuickNode Security Basics

Overview

Implementation patterns for QuickNode security basics using blockchain RPC endpoints and the QuickNode SDK.

Prerequisites

• Completed quicknode-install-auth setup

Instructions

Step 1: Connect to QuickNode

import { ethers } from 'ethers';
const provider = new ethers.JsonRpcProvider(process.env.QUICKNODE_ENDPOINT);
const block = await provider.getBlockNumber();
console.log(`Connected at block ${block}`);

Output

• QuickNode integration for security basics

Error Handling

Resources

• QuickNode Docs
• Ethereum API

Next Steps

See related QuickNode skills for more workflows.

QuickNode Upgrade Migration

Overview

Implementation patterns for QuickNode upgrade migration using blockchain RPC endpoints and the QuickNode SDK.

Prerequisites

• Completed quicknode-install-auth setup

Instructions

Step 1: Connect to QuickNode

import { ethers } from 'ethers';
const provider = new ethers.JsonRpcProvider(process.env.QUICKNODE_ENDPOINT);
const block = await provider.getBlockNumber();
console.log(`Connected at block ${block}`);

Output

• QuickNode integration for upgrade migration

Error Handling

Resources

• QuickNode Docs
• Ethereum API

Next Steps

See related QuickNode skills for more workflows.

QuickNode Webhooks Events

Overview

Set up QuickNode Streams for real-time on-chain event processing with custom filters and webhook delivery.

Prerequisites

• QuickNode account with Streams access
• HTTPS webhook endpoint

Instructions

Step 1: Create a Stream via Dashboard

1. Dashboard > Streams > Create Stream
2. Select chain: Ethereum Mainnet
3. Filter: Contract events for specific address
4. Destination: Webhook URL
5. Set payload format: JSON

Step 2: Handle Stream Events

import express from 'express';

const app = express();
app.post('/webhooks/quicknode', express.json(), async (req, res) => {
  const events = req.body;
  for (const event of events) {
    console.log(`Block: ${event.blockNumber}`);
    console.log(`TX: ${event.transactionHash}`);
    console.log(`Topics: ${event.topics}`);
    // Process on-chain event
    await processBlockchainEvent(event);
  }
  res.status(200).json({ received: true });
});

Step 3: Filter by Contract Events

// Stream filter function (runs on QuickNode infrastructure)
function main(data) {
  const targetContract = '0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48'; // USDC
  const transferTopic = '0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef';
  
  return data.streamData.filter(tx => {
    return tx.logs?.some(log =>
      log.address.toLowerCase() === targetContract.toLowerCase() &&
      log.topics[0] === transferTopic
    );
  });
}

Output

• Real-time blockchain event streaming
• Custom filter functions for specific contracts/events
• Webhook delivery for processed events

Error Handling

Resources

• QuickNode Streams
• QuickNode Docs

Next Steps

Optimize performance: quicknode-performance-tuning