--- title: Agent Subscriptions description: Create a Quicknode account and subscription programmatically using x402 or MPP payments. Receive a full platform API key and provision RPC endpoints without human signup. tags: [] --- ## Overview > For the complete documentation index, see [llms.txt](/docs/llms.txt) 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](/docs/build-with-ai/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](/docs/admin-api), set up [Streams](/docs/streams) and [Webhooks](/docs/webhooks), query with [SQL Explorer](/docs/sql-explorer), and read/write to the [Key-Value Store](/docs/key-value-store) Other Agentic Payments options For per-RPC-call access without creating an account, see [x402](/docs/build-with-ai/x402-payments) and [MPP](/docs/build-with-ai/mpp-payments). All three are part of [Agentic Payments](/docs/build-with-ai/agentic-payments). ## Prerequisites - A funded wallet on a [supported payment network](/docs/build-with-ai/agentic-payments) with a supported stablecoin - One of the Quicknode payment SDKs: - x402: [`@quicknode/x402`](https://www.npmjs.com/package/@quicknode/x402) - MPP: [`mppx`](https://www.npmjs.com/package/mppx) plus [`viem`](https://www.npmjs.com/package/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](/docs/streams) and [Webhooks](/docs/webhooks), write to the [Key-Value Store](/docs/key-value-store), manage teams and billing through the [Admin API](/docs/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](https://www.quicknode.com/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](#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](/docs/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: ```bash npm install @quicknode/x402 ``` Run the script: ```typescript 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: ```bash npm install mppx viem ``` Run the script: ```typescript 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`](https://github.com/quiknode-labs/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](https://www.quicknode.com/guides/solana-development/ai-agents/how-to-access-solana-rpc-with-x402-solana) guide for setup details. ```bash 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](/docs/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: ```json { "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: ```json { "data": { "id": "", "label": null, "status": "active", "chain": "base", "network": "mainnet", "http_url": "https://.base-mainnet.quiknode.pro//", "wss_url": "wss://.base-mainnet.quiknode.pro//", "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//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. ```bash 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. ```text PAYMENT-SIGNATURE: ``` The payload structure and signing rules are defined by the [x402 specification](https://github.com/coinbase/x402). For background on how the SDK assembles it, see [x402 Payments](/docs/build-with-ai/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. ```text Authorization: Payment ``` The credential format and challenge response are defined by the [MPP IETF Internet-Draft](https://datatracker.ietf.org/doc/draft-ryan-httpauth-payment/). For background on how the SDK handles it, see [MPP Payments](/docs/build-with-ai/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** ```typescript 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** ```typescript // 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. ```typescript 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](https://www.quicknode.com/api-docs/v0/swagger.json) 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](/docs/admin-api) and the [full spec](https://www.quicknode.com/api-docs/v0/swagger.json) for all available operations. ## Resources [ agents.md Full Agent API surface: auth methods, rate limits, pricing, supported chains →](https://www.quicknode.com/agents.md)[ create-endpoint.md Step-by-step walkthrough with curl examples and response shapes →](https://www.quicknode.com/agents/create-endpoint.md)[ x402 Payments Per-request RPC access via the x402 protocol →](https://www.quicknode.com/docs/build-with-ai/x402-payments)[ MPP Payments Per-request RPC access via the Machine Payments Protocol →](https://www.quicknode.com/docs/build-with-ai/mpp-payments)[ Admin API Docs Manage endpoints, billing, security, and teams via the Admin API →](https://www.quicknode.com/docs/admin-api)[ Admin API Swagger Spec Full OpenAPI specification for the Admin API →](https://www.quicknode.com/api-docs/v0/swagger.json)[ Pricing Available plans and pricing →](https://www.quicknode.com/pricing) tip For managing Quicknode infrastructure through natural language, see [Quicknode MCP](/docs/build-with-ai/quicknode-mcp). ## We ❤️ Feedback! If you have any feedback or questions about this documentation, [let us know](https://airtable.com/shrfIppvMmbdWxHgC). We'd love to hear from you!