What the integration covers

MCP server monetization with Blockchain0x is a pattern, not a package. You run your server over the Streamable HTTP transport and mount the x402 server adapter from @blockchain0x/x402 on the routes you want paid. That gives a free MCP server four things: a real HTTP 402 on gated routes, server-side verification of the payment, clean coexistence of free and paid routes, and per-call settlement in USDC on Base.

The design principle is that your server already knows how to expose tools. The adapter only adds the payment-required response and the verify-on-retry path. Transport, schemas, descriptions, and agent-side discovery keep working unchanged. This is the integration-cluster reference; the task walkthrough is how-to-add-payments-to-mcp-server, the strategy framing is how-to-monetize-mcp-server, and the MCP integration page is the canonical reference.

Compatibility matrix

The adapter gates at the HTTP layer, so it covers transports that ride HTTP.

What is not in scope:

• Per-tool-name pricing on a single JSON-RPC path. Pricing is by route, so split premium tools onto their own paths.
• Subscriptions and recurring billing. The model is per call. For human-driven subscription access, layer Stripe on top.

Surface area in one screen

The whole integration on one route is small. Build the client, register the adapter, keep your handler.

import Fastify from "fastify";
import { createClient } from "@blockchain0x/node";
import { createX402Plugin } from "@blockchain0x/x402/server/fastify";

const sdk = createClient({ apiKey: process.env.B0X_API_KEY! }); // sk_test_ -> Base Sepolia
const app = Fastify();

await app.register(createX402Plugin, {
  sdk,
  defaultNetwork: "testnet",
  pricing: {
    "POST /mcp/premium": {
      amountUsdc: "0.005",
      payToAddress: process.env.B0X_PAYTO_ADDRESS!,
      paymentRequestId: process.env.B0X_PRICE_REQUEST_ID!,
    },
  },
});

app.post("/mcp/premium", async (req) => handleMcpRequest(req.body)); // your handler, unchanged
await app.listen({ port: 8080 });

The Express shape is the same idea with createX402Middleware. The full code, including the exact 402 wire body and a free route alongside the paid one, is in how-to-add-payments-to-mcp-server.

Free and paid coexist by route. A route absent from the pricing table is never gated, so your discovery and cheap tools answer normally while only the premium path charges. That is the whole mechanism for a freemium MCP server: one priced route, the rest open. Adding a second paid tier later is one more entry in the table, and removing one is deleting an entry. No migration, no schema change, no redeploy of the tools themselves, just an edit to the pricing map the adapter reads at registration.

How the server verifies payment

The key property: the server never trusts the caller's claim of payment. When the caller retries with an X-Payment header, the adapter parses it and calls paymentRequests.settle against Blockchain0x to confirm the on-chain transfer matches the quoted requirement (right amount, right network, right payment request). Only a confirmed payment reaches your handler. A missing, malformed, or mismatched payment is rejected with a fresh 402 and a reason you can log.

This matters because the alternative, trusting a client's claim to skip a network round trip, is the most common way paid integrations bleed revenue. The adapter does the strict thing by default. There is no client-trusted fast path to misconfigure, and because verification is a stateless call rather than a cached token, you do not have to reason about cache invalidation or a leaked long-lived receipt.

When verification fails, the adapter tells you why instead of returning a vague error. The reasons are header_missing (the caller never sent payment), header_malformed (the header was corrupt), requirement_mismatch (the payment did not match the quoted price or network), and settle_rejected (the chain refused the settle call). Log the reason on every non-2xx. In practice it cleanly separates "the caller has no wallet" from "the caller paid the wrong amount" from "the chain adapter is down", and those three have completely different responses. The first is expected traffic, the second is a client-side stale-price bug, and the third is an incident on your side or the network's.

What the integration does not touch

The pattern stays narrow. These parts of your MCP server are unaffected:

• Transport. Streamable HTTP and SSE work the same way; the adapter is just middleware in front.
• Tool registration. How you register tools is unchanged.
• Tool schemas and descriptions. They pass through; the adapter never edits them.
• Free routes. Unpriced routes return their normal responses with no adapter involvement.
• Telemetry. Your logs, traces, and metrics keep working; the adapter logs its own rejection reasons alongside.
• Server identity and deployment. Your process model, admin auth, and infrastructure do not change.

When this is the right integration

Three situations where this pattern is the right pick.

Some of your tools have real upstream cost. Premium data, paid models, expensive compute. The adapter turns each gated call into a wallet-settled transaction with no billing portal, no Stripe account, and no per-agent signup. The unit economics work because the agent pays at call time, not after a sales cycle.

You want monetization invisible to free users. Free routes keep returning 200 the way they always did. Gated routes 402 cleanly; wallet-equipped clients settle silently, and clients without wallets get a clear, machine-readable signal instead of a misleading error.

You want one billing surface for many agent buyers. Without this, every agent that wants your premium tool onboards through your auth flow. With it, any runtime that speaks x402, whoever built it and wherever it runs, can pay your route. The pattern is many-to-one by default.

Where it is not the right pick: a tool that costs nothing to run (gating adds friction without revenue), a server used only by your own org (no payment needed), or a B2B deal with one named customer (a contract plus Stripe is faster).

Pricing and tier choices

The pattern is free; you write code against open packages. What you pay is the wallet platform fee, set on the pricing page: Free is $0 per agent per month at a 5% transaction fee, Pro is $9 per agent per month at 2%, and Business is $29 per agent per month at 1%. The fee applies to the server's own agent profile, the one that receives the USDC.

For a brand-new server, Free is enough to prove monetization works. The rough crossover where Pro pays for itself is a few hundred dollars of monthly volume on that profile, the same math as the LangChain integration's tiers, because the fee schedule is shared. Most servers that earn anything real cross that line in the first month if the gated routes have demand. For the full decision framework on what to gate and what to charge, see how-to-monetize-mcp-server.