Overview

The Agent Subscription API (POST /api/v1/agent/subscriptions) creates a Quicknode account and activates a paid plan in a single HTTP request. Payment is settled via x402 or MPP using the same wallet-based payment SDKs you already use for agentic payments. The response returns a QN_* full platform API key that unlocks the full Quicknode product suite (RPC endpoints, Streams, Webhooks, SQL Explorer, Key-Value Store, Admin API), so the agent can provision infrastructure without a human signing up through the dashboard.

The same x402 and MPP protocols that gate per-request RPC access are reused here, but in a different mode: instead of paying for one RPC call with no persistent state, a single subscription payment creates a persistent account with plan-based rate limits and a long-lived API key.

TL;DR

• A single POST to /api/v1/agent/subscriptions with an x402 or MPP payment creates a Quicknode account synchronously and returns a QN_* full platform API key with no email confirmation or dashboard signup required
• Use the same payment SDKs as agentic payments (@quicknode/x402 or mppx); the SDK handles signing the 402 challenge so you never construct payment headers by hand
• Once you have the key, use the full Quicknode platform like any other account: provision RPC endpoints and configure security via the Admin API, set up Streams and Webhooks, query with SQL Explorer, and read/write to the Key-Value Store

Other Agentic Payments options

For per-RPC-call access without creating an account, see x402 and MPP. All three are part of Agentic Payments.

Prerequisites

• A funded wallet on a supported payment network with a supported stablecoin
• One of the Quicknode payment SDKs:
  • x402: @quicknode/x402
  • MPP: mppx plus viem for key handling
• Node.js 20+ (both SDKs depend on global fetch)

How It Works

The agent onboarding takes three steps. The 402 handshake and payment signing happen inside step 2; from your code's perspective, the SDK turns the whole exchange into a single fetch call.

1. (Optional) Discover plans. Send the subscription request without a payment header to receive a 402 response listing all available plans, prices, accepted payment networks, and payment recipients. Skip this if you already know the plan ID you want.
2. Create the subscription. The SDK detects the 402 challenge from the server, signs the payment with your wallet, retries the request, and returns the QN_* full platform API key. The Quicknode account is created synchronously in the same response.
3. Start using Quicknode. With the full platform API key, the agent has the same access as an account created through the dashboard signup flow: provision RPC endpoints, configure Streams and Webhooks, write to the Key-Value Store, manage teams and billing through the Admin API, and more. The Quick Start below provisions an RPC endpoint and calls eth_blockNumber as one concrete example, but the same key works against the rest of the platform identically.

Plans

Plan IDs sent in the plan_name field map to the public plan names on pricing:

plan_name	Public name
b6_build	Build
b6_accelerate	Accelerate
b6_scale	Scale
b6_business	Business

If you don't know which plan to use, see Discover Plans below; the server returns the live plan list as part of the 402 response.

Quick Start

The script below runs the full onboarding end-to-end: it creates the subscription with the payment SDK, then uses the returned QN_* full platform API key to provision an RPC endpoint and call eth_blockNumber against it as a smoke test. Endpoint provisioning is just one example of what the API key unlocks; the same key works against the rest of the Admin API.

Real funds required

Subscriptions are paid with real stablecoins on a mainnet payment network. The examples below pay with USDC on Base Mainnet (x402) and PathUSD on Tempo Mainnet (MPP). Make sure your wallet is funded on the chosen payment network before running the script.

x402

Install the SDK:

npm install @quicknode/x402

Run the script:

import { createQuicknodeX402Client } from '@quicknode/x402'

// 1. Configure the x402 client. The SDK signs and attaches the
//    PAYMENT-SIGNATURE header automatically on any request that
//    returns HTTP 402 from the Quicknode API.
const client = await createQuicknodeX402Client({
  baseUrl: 'https://www.quicknode.com',
  network: 'eip155:8453', // payment network: Base Mainnet
  evmPrivateKey: process.env.PRIVATE_KEY as `0x${string}`,
})

// 2. Create the subscription. The SDK handles the 402 challenge,
//    signs the payment with your wallet, and retries.
const subscriptionRes = await client.fetch(
  'https://www.quicknode.com/api/v1/agent/subscriptions',
  {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      plan_name: 'b6_build', // Build plan
      interval: 'monthly',
      email: 'agent-abc@example.com',
      password: process.env.ACCOUNT_PASSWORD,
      password_confirmation: process.env.ACCOUNT_PASSWORD,
      full_name: 'Autonomous Agent',
      name: 'Agent Account',
      billing_address: {
        line1: '123 Main St',
        city: 'New York',
        postal_code: '10001',
        country: 'US',
      },
    }),
  },
)

const { api_key } = await subscriptionRes.json()
// api_key: "QN_abc123..."

// 3. Create an RPC endpoint using the full platform API key.
const endpointRes = await fetch('https://api.quicknode.com/v0/endpoints', {
  method: 'POST',
  headers: {
    'x-api-key': api_key,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ chain: 'base', network: 'mainnet' }),
})

const { data } = await endpointRes.json()
const { http_url } = data

// 4. Send a JSON-RPC call to the new endpoint. The auth token is
//    embedded in the URL path, so no extra headers are required.
const rpcRes = await fetch(http_url, {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    jsonrpc: '2.0',
    method: 'eth_blockNumber',
    params: [],
    id: 1,
  }),
})

const { result } = await rpcRes.json()
console.log('Block number:', parseInt(result, 16))

MPP

Install the SDK:

npm install mppx viem

Run the script:

import { Mppx, tempo } from 'mppx/client'
import { privateKeyToAccount } from 'viem/accounts'

const account = privateKeyToAccount(process.env.PRIVATE_KEY as `0x${string}`)

// 1. Activate MPP. This polyfills globalThis.fetch so 402 challenges
//    are intercepted, signed, and retried automatically inside fetch.
Mppx.create({ methods: [tempo({ account })] })

// 2. Create the subscription. The polyfilled fetch detects the
//    402, signs the payment, and retries with the Authorization
//    Payment header.
const subscriptionRes = await fetch(
  'https://www.quicknode.com/api/v1/agent/subscriptions',
  {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      plan_name: 'b6_build', // Build plan
      interval: 'monthly',
      email: 'agent-abc@example.com',
      password: process.env.ACCOUNT_PASSWORD,
      password_confirmation: process.env.ACCOUNT_PASSWORD,
      full_name: 'Autonomous Agent',
      name: 'Agent Account',
      billing_address: {
        line1: '123 Main St',
        city: 'New York',
        postal_code: '10001',
        country: 'US',
      },
    }),
  },
)

const { api_key } = await subscriptionRes.json()
// api_key: "QN_abc123..."

// 3. Create an RPC endpoint using the full platform API key.
const endpointRes = await fetch('https://api.quicknode.com/v0/endpoints', {
  method: 'POST',
  headers: {
    'x-api-key': api_key,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({ chain: 'base', network: 'mainnet' }),
})

const { data } = await endpointRes.json()
const { http_url } = data

// 4. Send a JSON-RPC call to the new endpoint.
const rpcRes = await fetch(http_url, {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({
    jsonrpc: '2.0',
    method: 'eth_blockNumber',
    params: [],
    id: 1,
  }),
})

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

Paying with Solana?

Use @quicknode/x402-solana, the Solana Kit integration for x402 on Quicknode, to sign x402 payments with a Solana keypair instead of an EVM private key. Once configured, the subscription request body and Admin API steps are identical to the x402 example above. See the How to Access Solana RPC with x402 guide for setup details.

npm install @quicknode/x402-solana

After this runs, you have a Quicknode account on the chosen plan, an RPC endpoint URL, and a successful eth_blockNumber response. The agent now has the same access as any other Quicknode account: the api_key works against the full Admin API (multichain, security rules, additional endpoints, billing) and across the rest of the Quicknode product suite (Streams, Webhooks, Key-Value Store).

Subscription response

A successful subscription response looks like:

{
  "api_key": "QN_abc123...",
  "plan": "b6_build",
  "admin_api_docs": "https://www.quicknode.com/docs/admin-api"
}

Endpoint response

A successful endpoint creation response looks like:

{
  "data": {
    "id": "<endpoint_id>",
    "label": null,
    "status": "active",
    "chain": "base",
    "network": "mainnet",
    "http_url": "https://<name>.base-mainnet.quiknode.pro/<token>/",
    "wss_url": "wss://<name>.base-mainnet.quiknode.pro/<token>/",
    "security": {},
    "rate_limits": {},
    "tags": []
  },
  "error": null
}

wss_url is null on chains that do not support WebSocket. To enable multichain on the endpoint (a single URL that routes across all Quicknode-supported chains), call POST /v0/endpoints/<endpoint_id>/enable_multichain with the x-api-key header.

Discover Plans

If your agent needs to choose a plan dynamically, send the subscription request without a payment header. The server returns HTTP 402 with the available plans, accepted payment networks, asset contract addresses, and recipient (payTo) addresses in the body. A PAYMENT-REQUIRED header (base64-encoded x402 requirement) is also set.

curl -X POST https://www.quicknode.com/api/v1/agent/subscriptions \
  -H "Content-Type: application/json" \
  -d '{}'

The agent can parse the 402 body, pick a plan, and retry the request through the SDK.

API Reference

Endpoints

Method	Path	Auth	Purpose
POST	/api/v1/agent/subscriptions	Payment header (x402 or MPP)	Create account and subscription
POST	/api/v1/agent/top_up	API key + payment header	Add credits to an existing subscription
GET	/api/v1/agent/balance	API key	Read current credit balance

All endpoints share the same host: https://www.quicknode.com.

Subscription request body

Field	Required	Notes
plan_name	Yes	One of: b6_build, b6_accelerate, b6_scale, b6_business. Omit to receive a 402 listing all plans and prices.
interval	No	monthly (default) or yearly.
email	Yes	Used for account lookup and retry resumption.
password	Yes	Enables retry or resume if the request needs to be retried. Must be 8–64 characters and include at least one lowercase letter, one uppercase letter, one number, and one special character.
password_confirmation	Yes	Must match password.
full_name	Yes	Primary user's full name.
name	Yes	Account display name.
billing_address.line1	Yes	Street address.
billing_address.city	Yes
billing_address.postal_code	Yes
billing_address.country	Yes	ISO 3166-1 alpha-2 code (e.g. US, GB).

Payment headers (wire format)

The @quicknode/x402 and mppx SDKs construct these headers for you. This section is a reference for clients that need to integrate at the HTTP level (for example, a non-Node runtime or a custom proxy).

x402

The signed payment is sent as a PAYMENT-SIGNATURE header containing a base64-encoded x402 v2 payload. If the header is absent, the server returns HTTP 402 with the plan and payment requirement details, and a PAYMENT-REQUIRED header carrying the base64-encoded x402 requirement.

PAYMENT-SIGNATURE: <base64-encoded x402 v2 signed payload>

The payload structure and signing rules are defined by the x402 specification. For background on how the SDK assembles it, see x402 Payments.

MPP

The signed payment is sent as an Authorization: Payment header carrying the MPP credential. If the header is absent, the server returns HTTP 402 with a WWW-Authenticate: Payment challenge that includes the payment method, intent, amount, and recipient.

Authorization: Payment <mpp credential>

The credential format and challenge response are defined by the MPP IETF Internet-Draft. For background on how the SDK handles it, see MPP Payments.

Subscription Management

Top up credits

Adds credits to the subscription. Requires both the API key and a fresh payment header, so the SDK handles signing again.

x402

const topUpRes = await client.fetch(
  'https://www.quicknode.com/api/v1/agent/top_up',
  {
    method: 'POST',
    headers: {
      'x-api-key': api_key,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({ amount: 10.0 }),
  },
)

const { balance_cents } = await topUpRes.json()

MPP

// Mppx.create({ methods: [tempo({ account })] }) was already called in setup.
const topUpRes = await fetch(
  'https://www.quicknode.com/api/v1/agent/top_up',
  {
    method: 'POST',
    headers: {
      'x-api-key': api_key,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({ amount: 10.0 }),
  },
)

const { balance_cents } = await topUpRes.json()

Check balance

Read-only; only the API key is required.

const balanceRes = await fetch(
  'https://www.quicknode.com/api/v1/agent/balance',
  {
    headers: { 'x-api-key': api_key },
  },
)

const { balance_cents } = await balanceRes.json()

Manage endpoints

List, update, configure security, and delete endpoints via the Admin API at https://api.quicknode.com/v0/endpoints/{id}. See the full Admin API spec for available operations including security rules, rate limit overrides, tags, and multichain configuration.

Rate Limits

Endpoint	Limit	Scope
POST /api/v1/agent/subscriptions	20/min, 5/hour	IP + email
POST /api/v1/agent/top_up	30/min	API key
GET /api/v1/agent/balance	60/min	API key

Guard Rails

• Duplicate email protection: Attempting to create an account with an existing email returns an error. Use the email and password fields to resume a failed or retried request.
• No free trials: All subscriptions are production-grade from the first request.
• Password enables retry: If a request fails after payment is sent, retry with the same email and password to resume rather than create a duplicate account.
• Synchronous creation: Account creation and subscription activation happen in the same request. There is no async job or webhook to wait for.

What the Subscription Unlocks

After provisioning, the QN_* API key provides access to the full Quicknode platform via the Admin API:

• Endpoints: provision and manage blockchain endpoints across all supported chains and networks
• Security configuration per endpoint: allowlists, JWT auth, origin restrictions
• Rate limit configuration per endpoint
• Full product suite: access all Quicknode products with API support
• Admin API surface: usage monitoring, billing, team management

See the Admin API docs and the full spec for all available operations.

Resources

agents.md

Full Agent API surface: auth methods, rate limits, pricing, supported chains

→

create-endpoint.md

Step-by-step walkthrough with curl examples and response shapes

→

x402 Payments

Per-request RPC access via the x402 protocol

→

MPP Payments

Per-request RPC access via the Machine Payments Protocol

→

Admin API Docs

Manage endpoints, billing, security, and teams via the Admin API

→

Admin API Swagger Spec

Full OpenAPI specification for the Admin API

→

Pricing

Available plans and pricing

→

tip

For managing Quicknode infrastructure through natural language, see Quicknode MCP.

We ❤️ Feedback!

If you have any feedback or questions about this documentation, let us know. We'd love to hear from you!