Skip to content

internet-court/internet-court-skill / vendored/quicknode/quicknode-skill

quicknode-skill

Verified

Quicknode blockchain infrastructure for 80+ chains: Core RPC API, Streams, Webhooks, Blazar WSS, Solana gRPC, HyperCore gRPC, SQL Explorer, Metaplex DAS API, Blockbook, Ordinals & Runes API, Swap API, x402, MPP, Agent Subscriptions, CLI, and MCP. Use for any Quicknode product, blockchain data access, or wallet-paid agent access.

references/x402-reference.md

View on GitHub
# x402 Reference

x402 enables wallet-based RPC access via stablecoin payments. No API key required. Three payment models: pay-per-request (no auth), nanopayment (batched via Circle Gateway), and credit drawdown (SIWX auth + credit bundle).

## Overview

| Property | Value |
|----------|-------|
| **Protocol** | HTTP 402 Payment Required |
| **Payment Models** | Pay-per-request, Nanopayment, Credit Drawdown |
| **Authentication** | None (pay-per-request, nanopayment) or SIWX + JWT (credit drawdown) |
| **Supported Protocols** | JSON-RPC, REST, gRPC-Web, WebSocket (varies by payment model) |
| **Payment Networks** | Varies by payment model. See [Payment Networks](#payment-networks-caip-2) |
| **Chains** | All Quicknode-supported networks |
| **Base URL** | `https://x402.quicknode.com` |
| **Use Cases** | Keyless RPC access, AI agents, pay-as-you-go, ephemeral wallets |

## Payment Models

| Model | Auth | Cost | Protocols | Best For |
|-------|------|------|-----------|----------|
| **Pay-per-request** | None | $0.001/request | JSON-RPC, REST | Simple integrations, low volume |
| **Nanopayment** | None | $0.0001/request | JSON-RPC, REST | High-volume testing (EVM testnets only for payment chain) |
| **Credit Drawdown** | SIWX + JWT | Testnet: $1/100,000 credits. Mainnet: $10/1,000,000 credits | JSON-RPC, REST, gRPC-Web, WebSocket | Sustained usage, streaming protocols |

The payment chain does not need to match the chain you query. For example, you can pay with Base Sepolia USDC and query Ethereum Mainnet.

### Credit Drawdown Flow

1. **Authenticate** via SIWX to get a JWT (1 hour expiry)
2. **Make a request** that returns HTTP 402 with payment requirements
3. **Pay** with a supported stablecoin to receive a credit bundle
4. **Consume credits** per successful response; when depleted, step 2 repeats automatically

### Pay-per-request Flow

1. **Make a request** (no auth needed); server returns HTTP 402
2. **Pay** with a payment signature included in each request (handled automatically by the client)

## Key Endpoints

| Endpoint | Method | Description |
|----------|--------|-------------|
| `/auth` | POST | Exchange SIWE/SIWX message + signature for JWT (public, no auth). Optional `type: "siwx"` field enables multi-chain auth |
| `/credits` | GET | Check credit balance (JWT required) |
| `/drip` | POST | Testnet USDC faucet (Base Sepolia only, requires JWT) |
| `/networks` | GET | List all supported network slugs (public, rate limited) |
| `/:network` | POST | JSON-RPC/REST proxy to Quicknode. Anonymous requests return 402 with payment requirements and extensions |
| `/:network/ws` | GET | WebSocket JSON-RPC proxy (JWT required, credits must exist) |
| `/sql/rest/v1/clusters` | GET | List Quicknode SQL Explorer clusters (public, 1-hour CDN cached) |
| `/sql/rest/v1/schema` | GET | List SQL Explorer schemas across clusters (public, 1-hour CDN cached) |
| `/sql/rest/v1/schema/:clusterId` | GET | Inspect one SQL Explorer cluster schema (public, 1-hour CDN cached) |
| `/sql/rest/v1/query` | POST | Paid SQL Explorer query endpoint; SIWX drawdown only, variable per-query credit cost |
| `/sql/rest/*` | ALL | Paid SQL Explorer REST pass-through; paths mirror `https://api.quicknode.com/sql/rest/*` |
| `/discovery/resources` | GET | Bazaar-compatible catalog of supported networks and payment requirements |
| `/openapi.json` | GET | OpenAPI 3.1 spec with x402 payment annotations |

## Testnet Monthly Cap

Each wallet gets a **single pool of 1,000,000 API credits per month** across Quicknode's agentic payment surfaces, including x402 and MPP. The pool resets on the 1st of each month and covers both RPC and SQL Explorer calls. Mainnet wallets are uncapped.

| Testnet Pool | Value |
|-----------------|-------|
| Credits per wallet | 1,000,000/month |
| Reset | 1st of each month |
| Scope | RPC + SQL Explorer |
| Shared across | Pay-per-request, Nanopayment, Credit Drawdown |

When the testnet cap is exhausted, requests return HTTP 403 `monthly_limit_reached` until reset. Switch to a mainnet-funded wallet for uninterrupted access.

## SQL Explorer

Quicknode SQL Explorer is exposed as a REST pass-through at `https://x402.quicknode.com/sql/rest/*`; every path mirrors the upstream `https://api.quicknode.com/sql/rest/*` route.

Free discovery endpoints require no auth and are cached for 1 hour:

- `GET /sql/rest/v1/clusters`
- `GET /sql/rest/v1/schema`
- `GET /sql/rest/v1/schema/:clusterId`

Paid SQL endpoints, such as `POST /sql/rest/v1/query`, require SIWX-authenticated credit drawdown. SQL cost is variable: the response's `credits` value is debited 1:1 from the caller's drawdown balance after the query runs. Because cost is only known after execution, per-request `PAYMENT-SIGNATURE` is not accepted for `/sql/rest/*`; authenticate with SIWX and pre-fund credits instead. An unauthenticated request, or a request that only presents `PAYMENT-SIGNATURE`, returns HTTP 402 with the SIWX drawdown extension and `use-drawdown` guidance.

## Rate Limits

| Route | Limit |
|-------|-------|
| `/auth` | 10 requests per 10 seconds per IP |
| `/credits` | 50 requests per 10 seconds per account |
| `/drip` | 5 requests per 60 seconds per account |
| `/networks` | 10 requests per 10 seconds per IP |
| `/:network` | 1,000 requests per 10 seconds per network:account pair |

Back off and retry on HTTP 429 `rate_limit_exceeded`. Error responses and JSON-RPC errors are not metered.

## Setup

### Install Dependencies

```bash
npm install @quicknode/x402
```

The `@quicknode/x402` package handles payment negotiation for all three models. For credit drawdown, it also manages SIWX authentication and JWT sessions.

### Create a Client and Make RPC Calls

```typescript
import { createQuicknodeX402Client } from '@quicknode/x402';

const X402_BASE_URL = 'https://x402.quicknode.com';

// Credit drawdown: preAuth authenticates (SIWX + JWT) upfront for faster payment flow
const client = await createQuicknodeX402Client({
  baseUrl: X402_BASE_URL,
  network: 'eip155:84532', // Base Sepolia (payment network)
  evmPrivateKey: process.env.PRIVATE_KEY as `0x${string}`,
  paymentModel: 'credit-drawdown',
  preAuth: true,
});

// Make RPC calls (payment is automatic on 402)
const response = await client.fetch(`${X402_BASE_URL}/ethereum-mainnet`, {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    jsonrpc: '2.0',
    id: 1,
    method: 'eth_blockNumber',
    params: [],
  }),
});

const { result } = await response.json();
console.log('Block number:', BigInt(result));
```

### Client Configuration

| Parameter | Description |
|-----------|-------------|
| `baseUrl` | The x402 gateway URL (`https://x402.quicknode.com`) |
| `network` | CAIP-2 chain identifier for the payment network |
| `evmPrivateKey` | Hex-encoded private key for EVM chains |
| `svmPrivateKey` | Base58-encoded secret key for Solana |
| `paymentModel` | `'pay-per-request'`, `'nanopayment'`, or `'credit-drawdown'` (default) |
| `preAuth` | Credit drawdown only. When `true`, pre-authenticates (SIWX + JWT) before the first request |

### Solana Client

```typescript
import { createQuicknodeX402Client } from '@quicknode/x402';

const client = await createQuicknodeX402Client({
  baseUrl: 'https://x402.quicknode.com',
  network: 'solana:EtWTRABZaYq6iMfeYKouRu166VU2xqa1', // Solana Devnet
  svmPrivateKey: '<YOUR_BASE58_SECRET_KEY>',
  preAuth: true,
});

// Query any chain (payment network doesn't need to match)
const response = await client.fetch('https://x402.quicknode.com/solana-devnet', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ jsonrpc: '2.0', id: 1, method: 'getSlot', params: [] }),
});
```

### Pay-per-request Client (No Auth)

```typescript
import { createQuicknodeX402Client } from '@quicknode/x402';

const client = await createQuicknodeX402Client({
  baseUrl: 'https://x402.quicknode.com',
  network: 'eip155:84532',
  evmPrivateKey: process.env.PRIVATE_KEY as `0x${string}`,
  paymentModel: 'pay-per-request',
});

const response = await client.fetch('https://x402.quicknode.com/base-mainnet', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ jsonrpc: '2.0', id: 1, method: 'eth_blockNumber', params: [] }),
});
```

### Nanopayment Client (Circle Gateway)

Nanopayment requires a one-time USDC deposit into the Circle Gateway Wallet contract. After depositing, the Gateway API waits for a chain-specific number of block confirmations before updating your unified balance. See [Circle's supported blockchains reference](https://developers.circle.com/gateway/references/supported-blockchains#required-block-confirmations) for confirmation times per chain.

```typescript
import { createQuicknodeX402Client } from "@quicknode/x402";

const client = await createQuicknodeX402Client({
  baseUrl: "https://x402.quicknode.com",
  network: "eip155:84532", // Base Sepolia (must be a nanopayment-eligible EVM testnet)
  evmPrivateKey: process.env.PRIVATE_KEY as `0x${string}`,
  paymentModel: "nanopayment",
});

// Check Gateway Wallet balance and deposit if needed
if (client.gatewayClient) {
  const balances = await client.gatewayClient.getBalances();
  console.log("Gateway available:", balances.gateway.formattedAvailable);

  // 1 USDC = 1_000_000 base units (6 decimals)
  if (balances.gateway.available < 1_000_000n) {
    console.log("Depositing 1 USDC...");
    const deposit = await client.gatewayClient.deposit("1");
    console.log(`Deposit tx: ${deposit.depositTxHash}`);
  }
}

const response = await client.fetch("https://x402.quicknode.com/base-mainnet", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({ jsonrpc: "2.0", id: 1, method: "eth_blockNumber", params: [] }),
});

const data = await response.json();
console.log("Block:", data.result);
```

### Check Credit Balance (Credit Drawdown Only)

```typescript
const creditsResponse = await fetch('https://x402.quicknode.com/credits', {
  headers: { Authorization: `Bearer ${client.getToken()}` },
});
const { credits } = await creditsResponse.json();
console.log('Remaining credits:', credits);
```

### Get Free Testnet Credits (Base Sepolia Only)

```typescript
const dripResponse = await fetch('https://x402.quicknode.com/drip', {
  method: 'POST',
  headers: { Authorization: `Bearer ${client.getToken()}` },
});
const dripResult = await dripResponse.json();
console.log('Credits received:', dripResult);
```

## Payment Networks (CAIP-2)

| Network | CAIP-2 ID | Token | Pay-per-request | Credit Drawdown | Nanopayment |
|---------|-----------|-------|:---:|:---:|:---:|
| Base Sepolia | `eip155:84532` | USDC | Yes | Yes | Yes |
| Base Mainnet | `eip155:8453` | USDC | Yes | Yes | No |
| Polygon Amoy | `eip155:80002` | USDC | Yes | Yes | Yes |
| Polygon Mainnet | `eip155:137` | USDC | Yes | Yes | No |
| XLayer Testnet | `eip155:1952` | USDG | Yes | Yes | No |
| XLayer Mainnet | `eip155:196` | USDG | Yes | Yes | No |
| Arc Testnet | `eip155:5042002` | USDC | No | No | Yes |
| Solana Devnet | `solana:EtWTRABZaYq6iMfeYKouRu166VU2xqa1` | USDC | Yes | Yes | No |
| Solana Mainnet | `solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp` | USDC | Yes | Yes | No |

## Best Practices

1. **Start with pay-per-request** for simplicity (no auth needed), switch to credit drawdown for sustained usage or streaming protocols.
2. **Use testnet first.** Call `/drip` for Base Sepolia, or pre-fund other supported testnets with the required stablecoin before using mainnet.
3. **Use `preAuth: true`** with credit drawdown to speed up the first payment flow.
4. **Reuse session tokens.** The client caches JWTs automatically (1 hour expiry).
5. **gRPC-Web and WebSocket require credit drawdown.** Pay-per-request and nanopayment support JSON-RPC and REST only.
6. **Multi-protocol support.** The same client works with JSON-RPC, REST, gRPC-Web (`client.createGrpcTransport()`), and WebSocket (`client.createWebSocket()`).
7. **Discover dynamically.** Use `/networks`, `/discovery/resources`, or `/openapi.json` instead of hardcoding the supported network list.

## Documentation

- **x402 Platform**: https://x402.quicknode.com
- **x402 Documentation (llms.txt)**: https://x402.quicknode.com/llms.txt
- **@quicknode/x402 Package**: https://github.com/quiknode-labs/quicknode-x402
- **Examples**: https://github.com/quiknode-labs/qn-x402-examples
writing-skillsobra/superpowersUse when creating new skills, editing existing skills, or verifying skills work before deploymentStars: 322kUpdated Claude CodeCodexVerifiedInstall
xlsxanthropics/skillsUse this skill any time a spreadsheet file is the primary input or output. This means any task where the user wants to: open, read, edit, or fix an existing .xlsx, .xlsm, .xltx, .csv, or .tsv file (e.g., adding columns, computing formulas, formatting, charting, cleaning messy data); create a new spreadsheet from scratch or from other data sources; or convert between tabular file formats. Trigger especially when the user references a spreadsheet file by name or path — even casually (like "the xlsx in my downloads") — and wants something done to it or produced from it. Also trigger for cleaning or restructuring messy tabular data files (malformed rows, misplaced headers, junk data) into proper spreadsheets. The deliverable must be a spreadsheet file. Do NOT trigger when the primary deliverable is a Word document, HTML report, standalone Python script, database pipeline, or Google Sheets API integration, even if tabular data is involved.Stars: 198kUpdated Claude CodeCodexVerifiedInstall
shipping-and-launchaddyosmani/agent-skillsPrepares production launches. Use when preparing to deploy to production, or when asking what needs to be in place before shipping. Use when you need a pre-launch checklist, when setting up monitoring, when planning a staged rollout, or when you need a rollback strategy.Stars: 119kUpdated Claude CodeCodexVerifiedInstall
childhoodthedotmack/claude-memBabysit a shipped release after merge, publication, or deployment. Verify published packages, production behavior, installed plugins, and late CI or user reports until the observation window is clean; use babysit for PR readiness before release.Stars: 118kUpdated Claude CodeCodexVerifiedInstall