Metered calls with x402 and MPP
Charge for a sealed action per call, with no account, no API key and no invoice. The same 402 speaks x402 and MPP, the payment is an on chain transaction, and the response carries its hash.
Why a sealed action is worth metering
An agent that wants to bid, vote, commit or hold a message until a deadline needs two things it usually cannot have at the same time: privacy until the deadline, and a way to pay for the service without opening an account first. Signing up is the part that does not survive contact with an autonomous caller. It needs an email, a card, a dashboard and a human.
x402 removes that step by
using the status code HTTP already reserved for it. The server answers
402 Payment Required and says what it costs. The caller pays. The caller asks
again, carrying proof. Nothing is stored about who called, because nothing needed to be.
Peal is a good fit for that shape because a call here is a discrete unit of work with a real cost and a real result: one sealed payload, held until a condition, then opened with a proof. It is not a subscription to a dashboard, it is a thing that happens once.
Watch it happen
Three parties and eight messages. The diagram below is wired to the same events the payer emits while it is actually paying, so every beam that lights corresponds to a request that was really made, and the hash that lands in it is one you can open in the explorer.
- 1 ask POST /v1/x402/rounds, no payment
- 2 402 price, asset, payee, chain
- 3 fund tempo_fundAddress, no faucet form
- 4 pay ERC-20 transfer to the payee
- 5 mined the transfer lands in a block
- 6 retry X-PAYMENT: base64({txHash})
- 7 verify receipt, amount, payee, age
- 8 200 the work, plus the receipt
This runs for real. The page mints a keypair in this tab, asks Tempo to fund it, which the chain does for anyone with no faucet form and no account, pays the price above, and makes the call. The key never leaves the tab and is never written to storage. It costs you nothing.
How it works here
Every endpoint under /v1 is mounted a second time under
/v1/x402. Same handlers, same request, same response. The only difference is that
the metered twin answers 402 until it is shown a payment.
- Ask. Call
/v1/x402/roundswith no payment. You get a 402 whose body names the asset, the amount, the payee and the chain. - Pay. Send that ERC-20 transfer on Tempo. Gas there is itself an ERC-20, so the payment and its own gas come out of one balance.
- Ask again. Repeat the request with
X-PAYMENT: base64({"txHash":"0x…"}). - Get the work and the receipt. The response is the ordinary one, plus an
X-PAYMENT-RESPONSEheader carrying the transaction hash and an explorer link.
What the server checks
Before a paid call runs, the coordinator asks the chain four questions: has this hash been redeemed here before, did the transaction succeed, did it move at least the price in the right asset to the right payee, and did it land recently. An MPP payment must also carry its challenge's memo. Redemption is the database insert and the hash is the primary key, so one transaction buys exactly one call even if two requests race.
This is not the exact scheme, and it does not claim to be.
The x402 exact scheme on EVM has the payer sign an EIP-3009 authorisation which
a facilitator broadcasts. That needs a funded key on the server, and this coordinator holds
none. So the scheme is named tempo-transfer: the payer broadcasts, and the
server verifies against the chain. Same handshake, same settlement, reached from the other
side. Naming it exact would mislead a client that knows what that word means.
In your own code
The whole client is the 402, the transfer and the retry. Nothing else.
// 1. ask, and read the price out of the refusal
let res = await fetch('https://peal.network/v1/x402/rounds', {
method: 'POST',
headers: { 'content-type': 'application/json' },
body: JSON.stringify({ opens_in: 3600, tag: 'my-agent' }),
});
if (res.status === 402) {
const { accepts: [req] } = await res.json();
// 2. pay it: an ordinary ERC-20 transfer on the chain the 402 named
const hash = await wallet.writeContract({
address: req.asset,
abi: parseAbi(['function transfer(address,uint256) returns (bool)']),
functionName: 'transfer',
args: [req.payTo, BigInt(req.maxAmountRequired)],
});
await publicClient.waitForTransactionReceipt({ hash });
// 3. ask again, carrying the proof
res = await fetch('https://peal.network/v1/x402/rounds', {
method: 'POST',
headers: {
'content-type': 'application/json',
'x-payment': btoa(JSON.stringify({ txHash: hash })),
},
body: JSON.stringify({ opens_in: 3600, tag: 'my-agent' }),
});
}
const round = await res.json();
const receipt = JSON.parse(atob(res.headers.get('x-payment-response')));
console.log(round.id, receipt.explorer);
What a call costs
Ask GET /v0/x402 and it tells you, without having to trigger a 402 to find
out. That endpoint is free, because a price list nobody can read is not a price list.
Paying with MPP
The same 402 also speaks MPP,
the Machine Payments Protocol from Stripe and Tempo. Alongside the x402 body, every refusal
carries a WWW-Authenticate: Payment challenge, so a client that knows MPP can pay
without reading anything on this page. Same endpoints, same price, same payee.
- Ask. The 402's challenge names the method (
tempo), the intent (charge), an expiry, and a request with the amount, the currency, the recipient, the chain and a memo made for this challenge alone. - Pay. Call
transferWithMemoon the TIP-20 currency with that memo, and wait for the receipt. - Ask again. Repeat the request with
Authorization: Paymentand a credential that echoes the challenge and carries{"type":"hash","hash":"0x…"}. - Get the work and the receipt. The response carries a
Payment-Receiptheader naming the transaction.
The memo is what MPP adds. A transfer counts only if it carries the memo of the challenge it
answers, so a payment is tied to one request rather than to any recent transfer of the right
size. Challenges are stateless: the id is an HMAC over the challenge's fields, so
the server recognises its own challenges and refuses one with any field changed. A failed
payment comes back as a 402 with the spec's problem type and a fresh challenge, so the client
can try again in one step. This server accepts push mode, where the payer broadcasts the
transfer and presents its hash.
// 1. ask; the 402 carries an MPP challenge as well as the x402 body
const url = 'https://peal.network/v1/x402/rounds';
const init = {
method: 'POST',
headers: { 'content-type': 'application/json' },
body: JSON.stringify({ opens_in: 3600, tag: 'my-agent' }),
};
let res = await fetch(url, init);
const challenge = Object.fromEntries(
[...res.headers.get('www-authenticate').matchAll(/(\w+)="([^"]*)"/g)].map(([, k, v]) => [k, v]),
);
const fromB64url = (s) => atob(s.replace(/-/g, '+').replace(/_/g, '/'));
const toB64url = (s) => btoa(s).replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '');
const request = JSON.parse(fromB64url(challenge.request));
// 2. pay with the challenge's memo
const hash = await wallet.writeContract({
address: request.currency,
abi: parseAbi(['function transferWithMemo(address to, uint256 amount, bytes32 memo)']),
functionName: 'transferWithMemo',
args: [request.recipient, BigInt(request.amount), request.methodDetails.memo],
});
await publicClient.waitForTransactionReceipt({ hash });
// 3. ask again with the credential
const { id, realm, method, intent, expires } = challenge;
const credential = {
challenge: { id, realm, method, intent, request: challenge.request, expires },
payload: { type: 'hash', hash },
};
res = await fetch(url, {
...init,
headers: { ...init.headers, authorization: `Payment ${toB64url(JSON.stringify(credential))}` },
});
const receipt = JSON.parse(fromB64url(res.headers.get('payment-receipt')));
console.log(receipt.reference); // the transaction hash
Why MPP
Both protocols use the same status code, and Peal answers both. MPP is the one we would point a new integration at, for four reasons.
- Payment is an HTTP authentication scheme. The challenge arrives in
WWW-Authenticate, the credential goes back inAuthorization, and the receipt comes back inPayment-Receipt, the way HTTP already handles every other credential. It has been proposed to the IETF, and there are official client libraries for TypeScript, Python, Rust, Go and Ruby. - One payment answers one request. Every challenge carries its own memo, and a transfer counts only if it carries that memo. A payment cannot be dug up and reused for a different call, and the receipt names the exact challenge it settled.
- Nothing to remember between the 402 and the retry. The challenge is signed with an HMAC over its own fields, so the server recognises it when it comes back and refuses it if anything was changed, with no session and no table of open quotes.
- Failure is a step, not a dead end. A rejected payment comes back as a 402 with a standard problem type and a fresh challenge attached, so a client can pay again without asking first.
MPP is also method-agnostic: the same handshake carries cards through Stripe or other rails, chosen per challenge. Peal accepts the Tempo method today.
What people build with MPP
The pattern is worth something wherever the thing being paid for is a discrete action with a real cost, and the caller is an agent or a person who will not sit through a signup form. Five that fit.
Pay per bid, in a sealed auction
A bid costs a fraction of a cent to place. Bidders stay anonymous until the close, nobody opens an account, and the seller is not running a payments integration for a listing that might get four bids.
Why MPP: each bid gets its own challenge and its own memo, so the fee is tied to that bid and nothing else. A bidder cannot reuse one payment to place a second.
Anti-spam that does not need identity
Charging for a slot in a round makes flooding it expensive without a captcha, an account or a rate limit keyed to an address. A thousand junk submissions costs a thousand payments.
Why MPP: every submission needs a transfer carrying a memo the server just issued, so the cost of spam scales with the spam. It works without knowing who anyone is.
Agents committing to each other
Two autonomous parties agree a price or an action, seal it until a deadline, and settle the fee in the same step. Neither holds an account with the other, and neither can see the other's number before the reveal.
Why MPP: an agent cannot complete a signup flow, but
it can read a WWW-Authenticate header, sign a transfer and retry. The
Payment-Receipt it gets back is its proof of what it paid for.
Paid disclosure on a timer
A report, a price, a model output: sealed now, opened at a stated moment, with the fee collected when it is sealed rather than invoiced later. The buyer can verify the reveal happened on time and was not edited.
Why MPP: the payment and the commitment are one request, and the receipt names both the transaction and the challenge, so there is no window where one exists without the other.
Metering your own API, on this pattern
The most common use, and it does not involve paying us. The gateway here is a working reference: issue a signed challenge with a memo, verify the transfer on chain, redeem the hash once, then serve.
Why MPP: no keys to issue, no invoices to chase, no subscription for somebody who wanted one call, and a standard any MPP client already speaks.
What has settled here
Every payment this gateway has accepted, newest first. Each one is a transaction on a public chain, so this is the one number on the site that nobody has to take on trust.
loading…
The free API has not moved
Everything under /v1 is still free, still needs no key and still needs no
wallet. Metering is a second door on the same rooms, for people who want to charge for what
they build on this, or who want to see the handshake work before they do. The
API reference has a switch at the top that sends every run
button through the metered twin, so you can watch the same request take both paths.
Paid calls are counted on the activity dashboard. That number is the one thing on that page nobody has to take on trust: each one is a transaction on a public chain.