From API Keys to Onchain Micropayments: Migrating a SaaS Endpoint to x402

A Practical Guide for Decision Makers: Ditching API Keys for Onchain Micropayments

Are you ready to leave behind the hassle of managing API keys and subscriptions? In this guide, we’ll walk you through using per-request, onchain micropayments with the HTTP-native x402 protocol. You’ll discover how the entire process works, find out how to set up a production integration on Base/Solana, and get tips on what to keep an eye on when you finally go live.

---

Why migrate now

• You've got HTTP-native payments now! The x402 project is bringing the HTTP 402 Payment Required status back into the game, and it lays out a clear way for servers to ask for payment and for clients to respond--all done over plain HTTP, no need for accounts or API keys. Check it out here: (x402.gitbook.io)
• When it comes to settling transactions, it’s quick and predictable. On Base, you’re typically looking at about a 2-second wait for L2 block inclusion, and then it takes around 2 minutes for L1 batch inclusion to give you that solid finality. Plus, if you’re using Coinbase’s hosted service, they settle USDC on Base with zero facilitator fees. More details can be found here: (docs.base.org)
• The tools are actually here and come from multiple vendors. You've got neutral community documentation, CDP’s facilitator/API, third-party helpers like PayAI, and SDKs for Node/Python to speed up your time-to-value. Dive into it here: (x402.gitbook.io)

With this setup, you can bill based on calls, kilobytes, milliseconds, or tasks--no need to deal with issuing, rotating, and securing API keys, or managing a whole subscription system. Check it out on github.com!

---

The x402 mental model (in 45 seconds)

• So, a client hits up your endpoint.
• If they need to make a payment, you hit them back with an HTTP 402 response. This will include a Payment Required Response JSON that lays out the accepted payment options like network, asset, maxAmountRequired, payTo, mimeType, outputSchema, maxTimeoutSeconds, and so on. You can check out more details here: (github.com).
• The client then gives it another shot with an X-PAYMENT header. This includes a base64-encoded JSON “Payment Payload” that holds the scheme/network and a signed authorization (using EIP‑3009 on EVM) or a chain-specific payload. More info on that can be found here: (github.com).
• Your server takes care of verifying and settling the transaction through a facilitator’s /verify and /settle endpoints. After all that, you respond with a 200 OK and include the X-PAYMENT-RESPONSE, which contains the settlement details (like the transaction hash) as base64 JSON. You can find the specific details in the docs here: (docs.cdp.coinbase.com).

x402 works with any transport and chain, but right now, the go-to combo is USDC on Base. Check it out here: (docs.cdp.coinbase.com).

---

Choosing your rails: networks, assets, facilitators

• Network:
  • For production, we're going with the Base mainnet, which offers super speedy L2 block inclusion (about 2 seconds). It also brings enterprise-grade compliance and Know Your Transaction (KYT) features through CDP’s facilitator, plus you can enjoy fee-free USDC settlements at that facilitator layer. Check it out here: (docs.base.org)
  • If you're looking for low fees and plan on handling a lot of workloads, Solana is a solid choice. There are community facilitators out there, and the tools are starting to roll out. More info here: (x402.gitbook.io)
• Asset:
  • We’re using USDC on EVM, which leverages the ERC‑3009 “TransferWithAuthorization.” This nifty feature allows for gasless, signature-based transfers that the facilitator can submit for users. You can dive deeper into it here: (eips.ethereum.org)
  • For SPL tokens on Solana, we’ve got community and partner facilitators on board, and there's no need to worry about EIP‑712 domain configuration. Check out the details here: (x402.gitbook.io)
• Facilitator:
  • There's the CDP-hosted option, which supports both production and Base/Solana networks but requires CDP keys on the mainnet. Find out more here: (docs.cdp.coinbase.com)
  • If you're in for some testing, the community option on Base Sepolia/Solana devnet is perfect--no keys needed! More info here: (docs.cdp.coinbase.com)
  • And for those who want complete control, self-hosting is the way to go. You can customize it for any EVM/Solana setup. Learn more here: (docs.cdp.coinbase.com)

---

Migration blueprint: API keys → x402 in one sprint

Here's a reference migration for a single paid endpoint (like GET /v1/premium). You’ll want to follow this pattern for each route.

1) Add server middleware (Node/Express)

Install Packages and Set Up Payment Middleware

First things first, let’s get those necessary packages installed and get the payment middleware wired up. When you’re testing, you can use the community facilitator for the testnet. But when you’re ready to go live, remember to switch to CDP for the mainnet.

Here's what you need to do:

1. Install Packages: Make sure you have all the required packages installed. You can do this with the following command:

   npm install package-name

2. Wire the Payment Middleware: Next, connect the payment middleware to your application. This is crucial for handling transactions smoothly.
3. Testing on Testnet: When you’re in testing mode, stick with the community facilitator. It’s perfect for simulating your environment without any risks.
4. Switch to Mainnet: As soon as you’re confident everything’s running smoothly, swap out to CDP for the mainnet. This transition is vital for taking your application live with real transactions.

By keeping these steps in mind, you should be well on your way to integrating payments securely and efficiently!

npm install x402-express
# for CDP-hosted facilitator (mainnet)
npm install @coinbase/x402

import express from "express";
import { paymentMiddleware } from "x402-express";
// For mainnet with CDP (requires CDP_API_KEY_ID/SECRET):
// import { facilitator } from "@coinbase/x402";

const app = express();

app.use(
  paymentMiddleware(
    "0xYourReceivingAddress",
    {
      "GET /v1/premium": {
        price: "$0.01",            // or a TokenAmount in atomic units
        network: "base-sepolia",   // "base" on mainnet
        config: {
          description: "Premium JSON",
          mimeType: "application/json",
          maxTimeoutSeconds: 60,
          // outputSchema helps agents self-validate:
          outputSchema: { type: "object", properties: { data: { type: "string" } } }
        }
      }
    },
    { url: "https://x402.org/facilitator" } // community testnet facilitator
    // For mainnet: facilitator    // from @coinbase/x402
  )
);

app.get("/v1/premium", (req, res) => {
  res.json({ data: "Hello, paid world!" });
});

app.listen(4021);

This setup will give you an HTTP 402 error, which means "Payment Required," if the client hasn't made their payment yet. But no worries--when they retry, it'll accept an X-PAYMENT header. You can find more details here.

If you're using Python, both FastAPI and Flask have pretty similar middleware features. Check it out here: (x402.gitbook.io)

2) Understand the 402 response and the X-PAYMENT header

The 402 body lays out the accepted payment requirements like scheme, network, maxAmountRequired, payTo, asset, mimeType, outputSchema, and more. To get things rolling, clients need to whip up a Payment Payload and shoot it over in X-PAYMENT (base64 JSON). You can check out more details on this over at github.com.

On a successful transaction, send back a 200 OK response along with the X-PAYMENT-RESPONSE header. This should be a base64-encoded JSON that contains settlement details like the transaction hash. You can check out more about this on GitHub.

3) Update the client call sites (automatic retries with payment)

Wrap your client with a fetch or axios instance that’s tuned to handle 402 errors. Here’s how you can create a setup that detects a 402 status, signs an authorization, retries the request with the X-PAYMENT header, and decodes the X-PAYMENT-RESPONSE afterward.

import axios from 'axios';

const client = axios.create({
  // Your base config here
});

// Function to handle the 402 error
const handle402Error = async (error) => {
  if (error.response && error.response.status === 402) {
    const { data } = await signAuthorization(); // Function to handle signing the authorization

    const retryResponse = await client.request({
      ...error.config,
      headers: {
        ...error.config.headers,
        'X-PAYMENT': data.paymentToken, // Include the payment token
      },
    });

    const paymentResponse = decodePaymentResponse(retryResponse.headers['X-PAYMENT-RESPONSE']); // Decode the response

    return paymentResponse; // Return or process your payment response accordingly
  }

  throw error; // Rethrow if it's not a 402
};

// Add request and response interceptors
client.interceptors.response.use(
  response => response,
  async error => await handle402Error(error)
);

// Your signAuthorization and decodePaymentResponse functions go here

In this code, we create an axios client that includes error handling for 402 responses. If a 402 error comes up, we sign the authorization, include the X-PAYMENT token in the retry, and decode the response from X-PAYMENT-RESPONSE. Adjust the signAuthorization and decodePaymentResponse functions to fit your needs.

This setup makes your API calls robust against payment-related hiccups!

import { wrapFetchWithPayment, decodeXPaymentResponse } from "x402-fetch";
import { createWalletClient, http } from "viem";
import { privateKeyToAccount } from "viem/accounts";
import { baseSepolia } from "viem/chains";

const account = privateKeyToAccount(process.env.PRIVATE_KEY!);
const fetchWithPayment = wrapFetchWithPayment(fetch, account);

const resp = await fetchWithPayment("https://api.example.com/v1/premium");
const body = await resp.json();
const receipt = decodeXPaymentResponse(resp.headers.get("x-payment-response") || "");
console.log({ body, receipt });

These wrappers take care of the base64 header encoding and decoding, as well as verifying and settling transactions. You can check it out here.

4) Move to mainnet: facilitator and keys

• Change your network settings from base-sepolia to base and from solana-devnet to solana (if that’s relevant for you).
• Make sure to use CDP’s facilitator package and set up your CDP_API_KEY_ID and CDP_API_KEY_SECRET for production purposes. Check it out on npmjs.com.
• The CDP’s facilitator allows for fee-free USDC settlements on Base and comes with compliance and KYT guardrails. For more info, head over to docs.cdp.coinbase.com.

---

Pricing models and the right scheme

x402 is all about schemes. Today, we’re diving into two hands-on schemes that you’ll get to explore:

• exact: Here, the client pays the exact amount stated in the 402. This is perfect for fixed-price calls or files. It's also backed by EIP‑3009 on EVM. Check out the details here.
• upto: In this case, the client gives the go-ahead for a maximum amount. You’ll need to verify first, do the work, and then settle the exact payment. This option works great for dynamic workloads, like AI token usage or per-row scans. Learn more here.

Example (conceptually, in a nutshell): check → carry out the task → finalize the exact amount; turn it down if the final price goes over maxAmountRequired or if the authorization window runs out. (portal.thirdweb.com)

Notes on Tokens and Signatures (EVM)

Understanding Tokens

In the Ethereum ecosystem, tokens are basically digital assets that can represent a variety of things--from cryptocurrencies to assets and even voting rights in a decentralized organization. They follow certain standards, primarily:

• ERC-20: This is the most popular token standard, used for fungible tokens. Basically, these tokens are interchangeable, like how dollars work.
• ERC-721: This one’s for non-fungible tokens (NFTs). Each token is unique, think of digital art or collectibles.
• ERC-1155: This is a hybrid standard that can handle both fungible and non-fungible tokens. Super flexible!

You can check out more about these standards here for ERC-20, here for ERC-721, and here for ERC-1155.

Exploring Signatures

When it comes to transactions on the Ethereum blockchain, signatures are key. They ensure the authenticity and integrity of the data being sent. Here’s how they work:

1. Private Key: This is your secret code that you keep to yourself. It allows you to sign transactions and prove ownership of your tokens.
2. Public Key: This is derived from your private key and can be shared with anyone. It helps others verify the legitimacy of your signatures.
3. Digital Signature: When you want to send a transaction, you use your private key to create a digital signature. This signature can be validated by anyone using your public key.

In short, your private key is like your password, while your public key is like your email address that you can share without compromising security.

Token Interaction and Signatures

When you’re interacting with tokens on the EVM, you’ll need to handle tokens and signatures together. Here’s a simple flow:

• You create a transaction to transfer tokens.
• You sign the transaction with your private key.
• The transaction gets sent to the Ethereum network.
• Miners validate your transaction using your public key to verify the signature.

This whole process keeps your assets secure while allowing you to send and receive tokens seamlessly.

Summary

Tokens and signatures are fundamental to navigating the Ethereum ecosystem. Understanding how they work empowers you to engage confidently with digital assets.

For more in-depth info, don't forget to check out additional resources and documentation!

• USDC is rolling out ERC‑3009. Basically, your facilitator creates an EIP‑712 message for TransferWithAuthorization/ReceiveWithAuthorization, and then users can sign it off-chain. The facilitator covers the gas fees and takes care of the submission. You can dive deeper into it here: (eips.ethereum.org)
• If you're dealing with non‑USDC tokens, some stacks also have support for ERC‑2612 permit flows. Just make sure to check out your facilitator’s documentation for the specifics. (portal.thirdweb.com)

---

Security checklist (steal this for your runbook)

• Make sure to double-check everything against the Payment Requirements you shared: resource URL, payTo, asset address, and maxTimeoutSeconds--not just the amount. If anything doesn’t match up, it should be rejected. (github.com)
• Stick to authorization windows. EIP‑3009 uses validAfter/validBefore; if you get replays that fall outside the window or have already used nonces, reject them. (eips.ethereum.org)
• If you're settling payments into a smart contract, it’s a good idea to go with receiveWithAuthorization. This helps steer clear of the front-running risks highlighted in the security notes of EIP‑3009. (eips.ethereum.org)
• Don’t forget to include mimeType and outputSchema in your 402. This helps agents understand exactly what they’re purchasing and ensures the response is shaped as expected. It really cuts down on disputes and enhances the experience for agents. (github.com)
• When responding, make sure to return X-PAYMENT-RESPONSE with the transaction hash and network info. Also, log this to your billing ledger for easy reconciliation and refunds. (github.com)
• Idempotency is key: use your own idempotency key (like X-Idempotency-Key) and link it to the payment nonce to avoid duplicate work if clients decide to retry. This is a solid best practice and works well with x402’s nonce setup.
• Keep your existing WAF and rate limits in place for anti-abuse; x402 is here as a payment layer, but it’s not a complete solution for abuse mitigation.
• If you’re letting users have multi-credit or post‑paid options, make sure to encode and validate per-credit entitlements on the server side. Some community proxies can expose patterns that let folks reuse a single X-PAYMENT token until their credits run out. (docs.proxy402.com)

---

Operational expectations

• Latency Budget: When using Base, you can expect around a 2-second wait for durable L2 inclusion. Overall, most facilitator settlements usually wrap up in just a few seconds. Here’s something to think about:
  • Do you want to gate the response based on settlement (which gives you the lowest risk of fraud)? Or
  • For a more dynamic setup, should you verify first, do the necessary work, and then settle at the end (this offers the best user experience for those ever-changing jobs)? You can dive deeper into the details here: (docs.base.org)
• Observability: It's important to track those spans like “402 → verify → settle → 200/X-PAYMENT-RESPONSE.” Make sure to keep a record of the tx hash, payer info, and the network involved. A lot of clients offer handy decode helpers for X-PAYMENT-RESPONSE, making things easier for you. Check it out: (x402.gitbook.io)
• Compliance: The facilitator for CDP includes KYT/OFAC screening along with enterprise SLAs, which is super helpful for teams navigating US regulations. For more info, head over to: (docs.cdp.coinbase.com)

---

Concrete examples you can copy

Example 1 -- Minimal Express server (fixed price)

As mentioned earlier, the production bump involves switching the facilitator and the network. You'll see similar patterns when it comes to Next.js middleware and Hono/Cloudflare Workers. Check it out here: (x402.gitbook.io)

Example 2 -- Python FastAPI (fixed price)

from fastapi import FastAPI
from x402.fastapi.middleware import require_payment

app = FastAPI()
app.middleware("http")(
    require_payment(
        path="/v1/premium",
        price="$0.001",             # 0.1¢
        pay_to_address="0xYourAddress",
        network="base-sepolia",     # "base" on mainnet
    )
)

@app.get("/v1/premium")
def premium():
    return {"data": "paid content"}

This will give you a 402 response along with the payment requirements, and when you retry, it will accept X-PAYMENT. Once everything's successful, you'll get back a 200 response with X-PAYMENT-RESPONSE. Check out the details here.

Example 3 -- Dynamic pricing with upto (AI/token usage)

Pseudocode Shape:

Pseudocode is a great way to outline the logic of your program without getting bogged down in syntax. Here's a simple shape of how to structure your pseudocode:

1. Start with a Header
   • This should include the name of the program and a brief description of what it does.

   PROGRAM: Calculate Average
   DESCRIPTION: This program calculates the average of a list of numbers.

2. Define Variables
   • Clearly state what variables you'll be using and what they are for.

   DECLARE numberList AS ARRAY OF NUMBERS
   DECLARE total AS NUMBER
   DECLARE average AS NUMBER
   DECLARE count AS INTEGER

3. Initialize Variables
   • Set up your variables before you start processing.

   SET total = 0
   SET count = 0

4. Input Data
   • Describe how you'll get the data into your program.

   INPUT numberList

5. Process Data
   • Detail the steps to compute what you need.

   FOR EACH number IN numberList
       total = total + number
       count = count + 1
   END FOR

6. Calculate Average
   • Figure out that average!

   IF count > 0 THEN
       average = total / count
   ELSE
       average = 0
   END IF

7. Output Results
   • Show the result to the user.

   OUTPUT average

Example

Here’s how it all comes together:

PROGRAM: Calculate Average
DESCRIPTION: This program calculates the average of a list of numbers.

DECLARE numberList AS ARRAY OF NUMBERS
DECLARE total AS NUMBER
DECLARE average AS NUMBER
DECLARE count AS INTEGER

SET total = 0
SET count = 0

INPUT numberList

FOR EACH number IN numberList
    total = total + number
    count = count + 1
END FOR

IF count > 0 THEN
    average = total / count
ELSE
    average = 0
END IF

OUTPUT average

This simple layout makes it easier to understand the flow of your program without getting caught up in complicated code!

// 1) Client receives 402 with maxAmountRequired (e.g., $0.10)
// 2) Client sends X-PAYMENT authorizing up to that amount (scheme: "upto")
// 3) Server verify -> run -> settle exact

const verification = await facilitator.verify(payload, requirements); // scheme: "upto"
if (!verification.isValid) return res.status(402).json(paymentRequirements);

// Do the expensive work; compute final price in atomic units (≤ maxAmountRequired)
const atomic = computeAtomicPriceFromUsage(usage);

// Finalize the charge
const settlement = await facilitator.settle(payload, { ...requirements, maxAmountRequired: atomic });
if (!settlement.success) return res.status(402).json(paymentRequirements);

res.set("X-PAYMENT-RESPONSE", encodeSettlement(settlement));
return res.json(result);

Check out Thirdweb’s November 2025 update on dynamic pricing! The patterns we see here fit perfectly with AI inference workloads. You can find all the details in their update log.

---

Real-world deployments and patterns to consider

• RPC Aggregation (Production Pattern): Check out this x402-powered RPC gateway that channels requests through over 8 different providers like Helius, Triton, QuickNode, Alchemy, and Infura. It’s super cost-effective, charging about $0.0001 per call, and can settle in under 3 seconds. This setup showcases some cool features like autonomous, per-call billing without the hassle of API keys. Definitely worth checking out if you're into multi-provider, pay-per-call designs! (x402labs.cloud)
• Payment Channels on Solana (Experimental): If you’re looking for something cutting-edge, there’s this experimental Solana payment-channel model from x402 that aims for lightning-fast sub-10ms verification for API calls. It uses a single server method that can handle both on-chain “exact” and “channel” schemes. This could be perfect if you need ultra-low latency and are okay managing channel lifecycles. Give it a look! (boberpay.com)
• IoT/Offline Patterns: Imagine using BLE-based device flows that push authorization offline and later settle on Base or other chains. This is really useful for applications like robots and sensors. It’s a neat approach if you’re dealing with IoT! (x4pay.org)

---

Under the hood: what your team should know

• The Payment Required Response schema is pretty standard and can be expanded. You can show off the response schema and MIME type to help set expectations for both human users and AI agents. (github.com)
• The facilitator interface is straightforward--it’s just a couple of REST calls, POST /verify and POST /settle. It’s designed to be aware of the network and scheme, so you can easily switch vendors or self-host without messing with your application contract. (docs.cdp.coinbase.com)
• When it comes to EVM, EIP‑3009 is what makes x402's gasless transfer authorizations possible. Make sure to check out the security notes, which cover unique nonces, validAfter/validBefore, and recommend using receiveWithAuthorization in your contracts. (eips.ethereum.org)
• Over on Base, keep an eye on a ~2s L2 inclusion for what’s considered “confirmed” work, and expect around 2 minutes for the “anchored” state to Ethereum L1. A lot of SaaS solutions are taking advantage of that 2s gating for a snappy experience, while relying on ledger reconciliation for any outliers. (docs.base.org)

---

Migration risks and how to de-risk them

• Break-glass path: Set things up behind a proxy or use a feature flag. If there’s an issue with your facilitator or network, you can quickly switch over to a free tier or a temporary API-key check.
• Double-spend/replay: Keep your Payment Payload tightly linked to your resource string and payTo. Make sure you're tracking and rejecting any reused nonces. (github.com)
• Token surface area: If you're stepping outside the USDC bubble, make sure to double-check for ERC‑3009/2612 support and the domain parameters (like name/version) needed for EIP‑712 signing. (x402.gitbook.io)
• Contract settlement: If your endpoint kicks off on-chain actions, go ahead and use receiveWithAuthorization in your contracts. Don’t forget to simulate before you actually settle! (eips.ethereum.org)

---

Bonus: agent and marketplace readiness

• Agent-friendly: Our client SDKs for fetch/axios/Python make life easier by automatically managing the whole 402→X‑PAYMENT→X‑PAYMENT‑RESPONSE process. Plus, we’ve got the Model Context Protocol (MCP) in place, so agents can handle payments for tools on their own, but with some solid guardrails. You can get started here.
• Discovery: We’re rolling out the “Bazaar” concept, which means agents will be able to find x402 endpoints and their pricing without any hassle. We’re also planning to keep accurate metadata on things like descriptions, mimeType, and outputSchema up to date. Learn more about it here.
• Trust layer: The ERC‑8004 is getting some updates to streamline how agent identity, reputation, and validation work on EVM. While x402 takes care of the money transfers, 8004 will enhance discovery and feedback. If you're keen on getting agents to give you a thumbs-up with proof-of-payment, keep an eye on these developments. Check out more on this link.

---

What 7Block Labs recommends as “current best practice” (Dec 2025)

• Kick things off on Base using USDC and the CDP facilitator; you can switch to self-hosted or community facilitators when you really need those custom networks or policies. (docs.cdp.coinbase.com)
• Stick with "exact" for your fixed-price calls; but if you're dealing with AI or token-metered workloads, go for "upto"--just make sure to double-check before you dive in and settle up afterward. (portal.thirdweb.com)
• Don’t forget to include mimeType, description, maxTimeoutSeconds, and outputSchema in your 402. Trust me, these fields can really boost your "first-pay" success by clearing things up for both users and agents. (x402.gitbook.io)
• Make sure to log X-PAYMENT-RESPONSE and show the tx hash in user dashboards. This keeps receipts transparent and speeds up support. (github.com)

---

A conservative two-week rollout plan

• Days 1-3: Start by getting the testnet integration going with Base Sepolia. Wrap one low-risk endpoint using the x402 middleware, and set up those dashboards to parse the X-PAYMENT-RESPONSE. Check it out here: x402.gitbook.io
• Days 4-6: Time to update the client with x402-fetch/axios. Run a synthetic load test and tweak maxTimeoutSeconds and price to get everything just right. More info can be found at x402.gitbook.io
• Days 7-9: Flip the switch to mainnet with Base and the CDP facilitator. Don’t forget to add some guardrails, like a feature flag and a free-fallback path. You can find guidelines here: docs.cdp.coinbase.com
• Days 10-14: Let's crank it up a notch! Expand your coverage to 3-5 endpoints, try out the "upto" feature on a metered route, and make sure to add success receipts to that billing UI. Dive deeper here: portal.thirdweb.com

---

Closing thought

x402 lets you turn your API into a utility, charging one HTTP request at a time. It’s all about using open, composable infrastructure instead of dealing with proprietary accounts and keys. With just a quick tweak to your middleware and a client wrapper, you can get started with pay-per-call in just a few days. From there, you can easily move into dynamic pricing and agent-native commerce as your needs evolve. Check it out on GitHub!

---

References and specs cited

• Check out the x402 protocol - it covers everything from headers and schemas to the flow of Payment Requirements, X-PAYMENT, and X-PAYMENT-RESPONSE, along with the details on the /verify and /settle endpoints. You can dive into it all here.
• If you're getting started, there are community quickstarts to help both sellers and buyers, plus info on middleware and wrappers. Grab the guide here.
• For those involved with CDP, you’ll find useful info about facilitators, networks, and compliance notes. Check it out here.
• Curious about base finality timing? You can find all the details here.
• Want to understand EIP-3009? Get the lowdown on the fundamentals and security considerations here.
• Explore dynamic pricing (upto scheme) patterns--details are available here.
• Lastly, check out some real-world examples of x402 in action, including RPC aggregators, channels, and IoT. Take a look here.

---