Category Archives: 000API

000API, 01 - Core Concepts

Payment Flow

Welcome to the NZRT Wiki Podcast. Today we’re looking at Payment Flow.

Let me walk you through how the x402 payment protocol works from start to finish. It’s a six-step cycle, and once you see the whole picture, it clicks pretty quickly.

Step one: your client makes a plain request to an API endpoint. Think of it like knocking on a door — no money involved yet, just a standard request asking for a resource.

Step two: the server responds with a 402 status code, which means Payment Required. Along with that, the server sends back a response body that tells you exactly what it needs. It includes a version number for the x402 protocol, and a list of accepted payment options. Each option in that list carries several details: a payment scheme, the network to use, a maximum amount required, the specific resource you’re trying to access, a short description, the wallet address to pay, a timeout window in seconds, and the token contract address. There’s also an extra field that names the token — in this case USDC, version 2. One thing worth noting on the amount: it’s expressed in USDC atomic units, which use six decimal places. So a value of one thousand in that field actually equals just one tenth of a cent — about point zero zero one dollars.

Step three: your client creates a payment authorization and signs it. This uses a standard called EIP-712, which is a typed data signing method for Ethereum-compatible wallets. The authorization itself contains a few fields: the payer’s wallet address, the payee’s wallet address, the value being transferred, a valid-after timestamp, a valid-before timestamp, and a random nonce — a one-time value that prevents the same payment from being submitted twice. The client signs all of this with the payer’s private key, producing a cryptographic signature.

Step four: the client retries the original request, this time including that signed payment in a special header. The whole payment payload — which contains the protocol version, the scheme, the network, the signature, and the authorization details — gets encoded and attached to the request. It’s essentially the same knock on the door as before, except now you’re handing over your payment at the same time.

Step five: the resource server doesn’t verify the payment itself. Instead, it forwards the payment payload to a third-party facilitator service. The facilitator checks four things: whether the signature is valid, whether the authorization fields are correct, whether the nonce has already been used, and whether the amount is sufficient. It then responds with either a confirmation that everything checks out, or an error explaining what went wrong.

Step six: if the facilitator gives the green light, the resource server does three things in sequence. First, it calls the facilitator’s settle endpoint, which actually executes the on-chain USDC transfer. Second, it returns the content you originally requested with a 200 OK response. And third, it includes a response header containing the blockchain transaction hash, so you have a receipt for the payment.

Now let’s talk about payment schemes and networks. Currently there is only one supported scheme, called exact. This means you pay a precise USDC amount using a transfer method defined in the EIP-3009 standard. Future versions of the protocol may support streaming micropayments and subscriptions, but for now, exact is the only option in the spec.

For networks, there are two supported options. You have the network identifiers, each pairing a chain with a specific USDC token contract address. The first is Base mainnet, and the second is Base Sepolia, which is the testnet version — useful for development and testing before you go live with real funds.

Finally, a quick note on caching. Clients are allowed to cache payment authorizations for the same resource, as long as you’re still within the valid-before time window. However, each authorization is strictly single-use. The nonce mechanism ensures that once a payment has been settled on-chain, it cannot be replayed. So caching helps you avoid redundant signing, but you can never reuse a nonce that’s already been spent.

That’s it for this episode of the NZRT Wiki Podcast. Thanks for listening.

000API, 02 - Protocol

Protocol Reference

Welcome to the NZRT Wiki Podcast. Today we’re looking at Protocol Reference.

This episode walks you through the x402 payment protocol — the HTTP headers involved, what the payment objects contain, how the facilitator API works, and how to wire it all up with the official SDK. Let’s get into it.

Start with the headers, because they’re the backbone of the whole flow. When your client hits a protected endpoint without having paid, the server returns a 402 response. That response includes a header called X-Payment-Requirements, which carries a Base64-encoded block describing exactly what payment is needed. Once your client has sorted out the payment, it retries the original request with a header called X-Payment — also Base64-encoded — containing the payment details. If everything checks out, the server comes back with a 200, and includes a third header: X-Payment-Response, a Base64-encoded settlement confirmation. So to recap: requirements come down from the server, payment goes up from your client, and the settlement confirmation comes back down.

Now let’s look at what’s inside those Base64 blobs. The payment requirements object — the one you get in the 402 — contains a version number and an array of accepted payment options. Each option in that array tells you the payment scheme, which is called “exact”, the network identifier, the maximum amount required expressed in atomic units — and worth noting here, USDC uses six decimal places — the full URL of the protected endpoint, a human-readable description, the expected response type, the payee’s Ethereum address, a timeout window in seconds, the USDC contract address on that network, and optionally a name and version identifying the token. For USDC that version is two, following the EIP-3009 standard.

The payment payload — what your client sends back in that X-Payment header — also has a version number and a scheme field. The core of it is a payload section with two parts. First, a signature: a hex-encoded cryptographic signature proving you authorised the transfer. Second, an authorization block containing the payer’s address, the payee’s address, the amount in atomic units, two timestamps marking when the authorization becomes valid and when it expires, and finally a random nonce — a 32-byte hex value that ensures the same authorization can’t be replayed in a future request.

Moving on to the Facilitator API, hosted at x402.org/facilitator. This is the service that verifies and settles payments on your behalf, and it exposes two endpoints. The first is the verify endpoint. You post to it with the payment payload and the payment requirements, and it responds with a simple result: either the payment is valid, or it is not, along with a reason string if something went wrong. The second endpoint is settle. Same input structure, and if successful, the response tells you the transaction was successful, gives you the transaction hash, and confirms which network the settlement occurred on.

On the subject of error codes, here are the HTTP status codes you’ll encounter. A 402 with the requirements attached means you need to pay before proceeding. A 400 means your payment header was malformed and couldn’t be parsed at all. Another 402 can come back even after you’ve submitted payment, if the signature check failed. And a 200 means you’re good — content is returned. On the facilitator side, when a payment comes back as invalid, the reason will be one of five values: invalid signature, insufficient amount, expired, nonce already used, or invalid network.

Now for the cryptographic layer underneath all of this. x402 uses a standard called EIP-3009, specifically a typed data structure called TransferWithAuthorization. The signing domain is set up for USD Coin version two, on chain ID 8453 — that’s the Base network — pointing to the USDC contract address on that chain. The typed data itself defines six fields: the from and to addresses, the value as a large unsigned integer, two timestamp fields for the valid-after and valid-before window, and the nonce as a 32-byte value. This is the structure that the payer signs to produce the signature you saw in the payment payload object earlier.

Finally, if you’re working in TypeScript or JavaScript, there’s an official SDK available through npm. You import a middleware function from the x402 package, attach it to your Express application with your wallet address and a configuration object that maps your API routes to their prices and target networks, and the middleware handles everything from there — generating the 402 responses, calling the facilitator to verify incoming payments, and settling them automatically. You don’t need to manually wire up any of the facilitator calls if you’re using the SDK.

That’s it for this episode of the NZRT Wiki Podcast. Thanks for listening.

000API, 03 - MCP Integration

Mcp Integration

Welcome to the NZRT Wiki Podcast. Today we’re looking at MCP Integration.

So let’s start with why this matters. x402 — NZRT’s micropayment protocol — pairs naturally with MCP, which stands for Model Context Protocol. The idea is that the MCP server acts as the paying client, automatically handling payment responses in a way that’s completely transparent to the language model itself. The LLM never has to think about money — it just asks for something and gets an answer back.

Let’s walk through how that works in practice, starting with the architecture.

Picture Claude — the language model — calling a tool called search wiki, passing in a keyword like “kubernetes”. That call goes down to the MCP server, which is running locally on your machine. The MCP server then makes an HTTP request out to a resource server. The resource server comes back with a 402 status — that’s the standard HTTP code meaning payment required. The MCP server reads the payment requirements, signs a USDC authorization using its wallet, and retries the same request, this time including a payment header. The resource server accepts that, returns the actual content, and the MCP server passes the result back up to Claude as a normal tool result. Claude never sees the payment happen. It just gets its answer. That’s the elegance of this design.

Now let’s look at what the MCP server is actually responsible for. There are five main areas. First, tool exposure — it defines the tools that the language model can call. Second, it acts as the HTTP client, making requests to the resource server on Claude’s behalf. Third, it handles those 402 responses — detecting them, reading the payment requirements, signing the payment, and retrying. Fourth, it holds the payer wallet, meaning it stores the private key used to sign what’s called an EIP-712 payment authorization. And fifth, it manages nonces, generating a random value for each payment to prevent replay attacks.

Speaking of the tools the MCP server exposes, there are two defined in the schema. The first is called search wiki — its job is to search the NZRT knowledge vault by keyword, and it takes a single input, a search query string. The second tool is called get wiki note, which retrieves a specific note from the vault by its file path — something like Wiki slash Flarum slash HOME. Both tools require their input to be provided, so Claude always needs to pass either a query or a path when calling them.

Next, transport. You have two options for how an MCP server can run. The first is stdio, which is local — Claude Desktop spawns the MCP server process directly on the same machine. The second is SSE, which stands for Server-Sent Events and works over HTTP, letting a server run independently while Claude connects to it via a URL. For x402 MCP setups, stdio is the typical choice. The resource server itself can be remote or local, but the MCP server always runs local to wherever the LLM client is.

Now let’s talk about what actually triggers the automatic payment. When the MCP server makes a request and gets back that 402 status, it reads the payment requirements from the response body, signs a payment using the private key it holds, and retries the original request with a header called X-Payment carrying the encoded payment data. If everything checks out, the resource server responds with a 200 and the content, which flows back up to Claude as a normal result.

On the resource server side, you’ve got five responsibilities of its own. First, route protection — it returns 402 for any endpoint that requires payment. Second, payment verification — for each incoming payment header, it calls out to a facilitator service to verify the payment is valid. Third, settlement — once verified, it calls that same facilitator’s settle endpoint to actually execute the on-chain transfer. Fourth, content serving — after a verified payment, it returns the requested content. And fifth, there’s a free health check endpoint always available for monitoring, no payment needed.

So to pull it all together, MCP Integration with x402 creates a clean separation of concerns. Claude stays focused on reasoning and tool use. The MCP server handles all the payment plumbing invisibly in the background. And the resource server enforces access control and handles settlement. The whole thing is designed so that paid API access just works, without the LLM needing to understand anything about wallets, signatures, or blockchain transactions.

That’s it for this episode of the NZRT Wiki Podcast. Thanks for listening.

00 - Overview, 000API

X402 Overview

Welcome to the NZRT Wiki Podcast. Today we’re looking at x402 Overview.

So let’s start with the basics. x402 is an open protocol designed for machine-to-machine HTTP micropayments. The name comes from HTTP status code 402, which is called Payment Required — a code that’s been sitting in the HTTP specification for decades but was never seriously put to use. Until now.

The protocol was specified by Coinbase and lives on GitHub, and there’s a facilitator service running at x402.org that handles the verification side of things. We’ll get to what a facilitator does in a moment.

First, why does this exist? Think about how APIs are monetised today. You need to create an account, manage API keys, set up a billing system, choose subscription tiers, and build rate limiting infrastructure. That’s a lot of overhead — especially for automated systems or AI agents that just want to call an endpoint and get a result.

x402 strips all of that away. There are no accounts, because the payment itself acts as your authentication. There are no API keys, because your wallet signature proves you’ve paid. There’s no billing system, because payments happen per request on-chain. And crucially, it’s native to AI agents — machines can pay other machines automatically, with no human in the loop.

So how does it actually work? Here’s the flow. A client makes a request to a paid endpoint. The server responds with that HTTP 402 Payment Required status, and includes a set of payment requirements — how much to pay, which network to use, and which wallet address receives the funds. The client then creates a signed USDC transfer using a standard called EIP-712, which is a typed signature format for Ethereum-based transactions. The client attaches that signed authorisation to a second request and retries the call. The server takes that payment header and forwards it to a facilitator, which is an off-chain service that checks the signature. Once the facilitator confirms everything is valid, the server delivers the content.

The important thing to note is that verification happens off-chain, so there is no gas cost just to verify a payment. And there’s only one extra round-trip per uncached request, which keeps latency manageable.

Now let’s talk about where you’d actually use this. There are five key use cases. First, API monetisation — any HTTP endpoint can become a pay-per-request service. Second, AI agent tooling — agents can automatically pay for the tools and data they need. Third, knowledge base access — you could charge a small amount per document retrieval, like a wiki search. Fourth, metered compute — paying per AI inference, per render, or per export. And fifth, content paywalls — charging a micropayment for access to an article, a report, or a dataset.

The protocol is built on two specific technologies that make micropayments practical. The blockchain is Base, an Ethereum Layer 2 network backed by Coinbase. Gas fees on Base are fractions of a cent, which is what makes tiny payments economically viable. The currency is USDC, Circle’s stablecoin that tracks one-to-one with the US dollar and is native to EVM-compatible chains. On Ethereum mainnet, a payment of a fraction of a cent would cost more in gas than the payment itself — Base solves that entirely.

Finally, there are six key concepts worth locking in. The resource server is the HTTP server that enforces payment — it responds with the 402 and ultimately delivers your content. The facilitator is the off-chain service that verifies payment signatures, acting as the trust layer between client and server. Payment requirements are the details returned in that 402 response — the amount, network, asset type, and payee address. The payment authorisation is the signed transfer the client attaches to its retry request. The payee is the EVM wallet address receiving the USDC. And the payer is the EVM wallet address doing the paying — it signs the transfer to authorise the whole thing.

That’s it for this episode of the NZRT Wiki Podcast. Thanks for listening.