Pay per request with x402

Call any billable Particle Pro endpoint without an account by paying per request in USDC over the x402 protocol — what the 402 challenge carries, what a call costs, and how an agent pays.

Agents with no human operator to mint an API key can still use Particle Pro. Every billable /v1/* endpoint and the MCP endpoint accept an x402 micropayment in place of a credential: the server answers a keyless call with 402 Payment Required and the payment terms, the agent signs a USDC transfer for exactly that amount, and the retried request is served once the payment is verified.

No sign-up, no key, no invoice — each request pays for itself, on-chain, at the time of the call.

How it works

1. Call the endpoint with no credential

   curl -i "https://api.particle.pro/v1/podcasts/search?q=artificial%20intelligence"
   

   HTTP/1.1 402 Payment Required
   Content-Type: application/problem+json
   Cache-Control: no-store
   PAYMENT-REQUIRED: eyJ4NDAyVmVyc2lvbiI6MiwiYWNjZXB0cyI6W3sic2NoZW1lIjoiZXhhY3QiLC…
   
   {
     "status": 402,
     "error_code": "payment_required",
     "detail": "This request costs $0.01 in USDC. Pay per request with x402 — the PAYMENT-REQUIRED response header carries the payment requirements — or authenticate with a pp_ API key.",
     "resolve": { "action": "pay_per_request", "url": "https://docs.particle.pro/x402", "message": "…" }
   }
   

   The PAYMENT-REQUIRED header is base64-encoded JSON in the x402 v2 shape. Decoded:

   {
     "x402Version": 2,
     "resource": { "url": "https://api.particle.pro/v1/podcasts/search?q=…", "description": "Podcast, people, company and topic intelligence — …" },
     "accepts": [{
       "scheme": "exact",
       "network": "eip155:8453",
       "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
       "amount": "10000",
       "payTo": "0x…",
       "maxTimeoutSeconds": 60,
       "extra": { "name": "USD Coin", "version": "2" }
     }]
   }
   

   amount is in the asset’s smallest unit — USDC has six decimals, so 10000 is $0.01.

2. Sign the payment and retry

   Sign an EIP-3009 transferWithAuthorization for the accepted option (an x402 client library does this for you), base64-encode the payment payload, and repeat the identical request with it in the PAYMENT-SIGNATURE header.

3. Receive the response and the receipt

   The facilitator verifies the signature and the payer’s balance, the request runs, and the transfer is settled on Base. The response carries a PAYMENT-RESPONSE header (base64 JSON) with the settlement transaction hash, the network and the payer.

   HTTP/1.1 200 OK
   PAYMENT-RESPONSE: eyJzdWNjZXNzIjp0cnVlLCJ0cmFuc2FjdGlvbiI6IjB4…
   

A request that fails is never charged: settlement happens only after the handler produced a successful response, so a 404, 422 or 500 costs nothing. If settlement itself fails, the response is withheld and a 402 with a PAYMENT-RESPONSE error is returned. A rejection by the facilitator (for example the payer’s balance moved between verification and settlement) transfers nothing. If the failure was a timeout, the transfer may still have gone through, so retry the identical request with the same PAYMENT-SIGNATURE first: an EIP-3009 authorization executes at most once, so the replay either completes the settlement or is refused because it already did. Sign a new payment only after an explicit rejection.

Prices

Prices come from the same relative cost weights that price API-key plans, at one US cent per unit of weight:

Endpoint tier	Cost weight	Price per call
Standard	1	$0.01
Premium	2–3	$0.02–$0.03
MCP (POST /mcp)	flat	$0.01 per HTTP request

The exact amount for a call is always in its 402 — read it from accepts[].amount rather than hard-coding it. Payments are USDC on Base (eip155:8453); the facilitator sponsors gas, so the amount in the challenge is the whole cost.

What can be paid for

• Every standard and premium /v1/* endpoint listed in the API reference — podcasts, episodes, transcripts, guests, rankings, companies, people, topics.
• POST /mcp — see MCP below.

Some surfaces still need an account:

• Free endpoints are already keyless and stay free — they are never challenged.
• Alerts (/v1/alerts/*) create state that belongs to a project, so they require an API key.
• Account and dashboard routes authenticate a platform user session, which a payment cannot replace; they keep their usual 401.
• Enterprise-only surfaces such as the episode firehose stream, and streaming responses generally, are not payable per request.

Paying from an agent

Any x402 v2 client works. Point it at the API with a wallet that holds USDC on Base and it handles the challenge, the signature and the retry:

• Coinbase’s @x402/fetch / @x402/axios (TypeScript) and x402 (Python) packages, and the Go SDK.
• Agent frameworks with x402 built in — Coinbase AgentKit, the Coinbase Payments MCP, Vercel AI SDK’s x402 integration, Amazon Bedrock AgentCore Payments.
• Stripe’s purl for testing from the command line.

import { wrapFetchWithPaymentFromConfig } from "@x402/fetch";
import { ExactEvmScheme } from "@x402/evm";
import { privateKeyToAccount } from "viem/accounts";

const account = privateKeyToAccount(process.env.WALLET_PRIVATE_KEY);
const fetchWithPayment = wrapFetchWithPaymentFromConfig(fetch, {
  schemes: [{ network: "eip155:8453", client: new ExactEvmScheme(account) }],
});

const res = await fetchWithPayment(
  "https://api.particle.pro/v1/podcasts/search?q=artificial%20intelligence",
);
console.log(res.status, res.headers.get("PAYMENT-RESPONSE"));

Credentials always win

The payment path is strictly a fallback for requests that carry no credential. A request that presents anything that looks like a credential — an Authorization header, an X-API-Key header, or an api-key query parameter, even an invalid or expired one — takes the normal authentication path and gets the usual api_key_required 401, never a payment challenge. Keyed and OAuth traffic is unaffected by this feature.

MCP

A keyless POST to https://mcp.particle.pro/mcp is challenged the same way, at a flat price per HTTP request. The 402 carries both challenges so every kind of client can proceed:

• PAYMENT-REQUIRED — the x402 terms.
• WWW-Authenticate: Bearer realm="mcp", resource_metadata="…" — the RFC 9728 pointer OAuth clients follow.

Pricing is per HTTP request, so initialize, tools/list and each tools/call cost the flat price when paid this way. Notification-only POSTs (such as notifications/initialized) are acknowledged for free, and a tools/call whose result is an error — a JSON-RPC error or an isError tool result — is not charged: the PAYMENT-RESPONSE receipt then reports a waived settlement instead of a transaction. Tools that manage project-scoped state (the particle_alert_* family) cannot be paid per request; they answer with the usual authentication challenge. For interactive use, OAuth is cheaper and simpler; per-request payment is for autonomous agents that have no operator to approve a connection.

Discovery

An agent does not have to know Particle Pro exists to find it. Everything a keyless caller needs is published where x402 tooling looks:

• The 402 itself. Every challenge carries the Bazaar discovery extension: the endpoint’s method, an example input, the JSON schema of its parameters, and the service name, description and tags. The Coinbase facilitator catalogs an endpoint after its first settlement, so it appears in the x402 Bazaar search API (GET https://api.cdp.coinbase.com/platform/v2/x402/discovery/search?query=podcast) and in the Bazaar MCP server (https://api.cdp.coinbase.com/platform/v2/x402/discovery/mcp) that agent frameworks such as AWS AgentCore and the Coinbase Payments MCP query.
• /.well-known/x402 on api.particle.pro and mcp.particle.pro — the capability manifest from the x402 DNS discovery draft: protocol version, the payment terms every endpoint accepts (network, asset, recipient), and the payable resources with their prices. /.well-known/x402.json on the same hosts is the community endpoint list that x402 checkers and directories probe.
• OpenAPI. Every payable operation in https://api.particle.pro/openapi.json documents a 402 response and carries x-payment-info — the price in US dollars and x402 as the protocol — and info.x-guidance tells an agent how to start. Directories such as x402scan read this document first and the live 402 second.
• Agent onboarding. https://api.particle.pro/auth.md and llms.txt describe the payment path next to the credential paths.

Records and refunds

Every settlement is recorded with its transaction hash and booked to our accounts, so a receipt in PAYMENT-RESPONSE is a durable reference for support. There are no refunds for a response that was served; nothing is charged for one that was not.

See also

• payment_required — the error code and how to resolve it.
• Agent authentication — the full credential decision tree, including when to prefer an API key.
• x402 protocol and the x402 specification.