x402 - payment-required over HTTP
Dynamo speaks x402: HTTP 402 with a machine-readable challenge, answered by an X-PAYMENT header. Two schemes ride the same challenge:
exact- discrete work at a quoted price: the buyer ticks the price
against a stream, binds the payment to the seller's request nonce, and presents a receipt the engine signed for this sale (payee, resource, nonce, expiry). The seller accepts it only from engine signers it pins. Request-bound, replay-rejected, idempotent.
dynamo-allowance- streaming access: the buyer presents the offline
allowance credential; the seller meters actual work against it.
Everything the seller checks is verifiable offline against a pinned engine signer - no payment-network call in the request path. Status: Live (the sample below runs in Control Mode).
The full round trip
import { Dynamo, usd, units, x402 } from "@dynamoprotocol/sdk";
const dynamo = await Dynamo.open({
coreUrl: process.env.DYNAMO_CORE_URL!,
token: process.env.OWNER_API_TOKEN!,
});
const seller = "0x00000000000000000000000000000000000000D4";
const sleep = (ms: number): Promise<void> => new Promise((r) => setTimeout(r, ms));
// BUYER side: a capped stream aimed at the seller.
const budget = await dynamo.openBudget({ funding: "none", cap: usd("5") });
const stream = await budget.stream({ to: seller, rate: units(1_000_000n), cap: units(2_000_000n) });
await sleep(1_100);
// SELLER side: the 402 challenge for a priced resource.
const challenge = x402.issueChallenge({
resource: "https://api.example.test/report",
payTo: seller,
maxAmountRequired: 250_000n,
requestRef: "req-docs-1",
});
// BUYER: answer with the exact scheme - ticks the price, binds the receipt.
const answer = await x402.answerChallenge(challenge, stream, { prefer: "exact" });
if (answer.headerName !== "X-PAYMENT") throw new Error("payment rides X-PAYMENT");
// SELLER: verify ENTIRELY offline against the PINNED engine signer - the
// address your budget reported at open; operators pin it in config. The
// receipt must name this resource and this nonce, and the seller keeps a
// replay store: a nonce it has served is never served again.
const engineSigner = budget.engineSigner as `0x${string}`;
const consumed = new Set<string>();
const sellerChecks = {
expectedSigner: engineSigner,
trustedReceiptSigners: [{ address: engineSigner }],
serviceNode: seller,
expectedResource: "https://api.example.test/report",
expectedRequestRef: "req-docs-1",
requiredUnits: 250_000n,
isRefConsumed: (ref: string) => consumed.has(ref),
};
const verified = await x402.verifyPayment(answer.headerValue, {
...sellerChecks,
nowSeconds: BigInt(Math.floor(Date.now() / 1000)),
});
if (!verified.valid) throw new Error(`payment must verify: ${verified.reason}`);
if (verified.scheme !== "exact") throw new Error("expected the exact scheme");
consumed.add(verified.requestRef);
// The same payment presented again is a replay: refused, never served twice.
const again = await x402.verifyPayment(answer.headerValue, {
...sellerChecks,
nowSeconds: BigInt(Math.floor(Date.now() / 1000)),
});
if (again.valid) throw new Error("a replayed payment must be refused");
// The allowance is AIMED: a different service node replaying the same
// payment is refused with a named reason - never served.
const elsewhere = await x402.verifyPayment(answer.headerValue, {
...sellerChecks,
serviceNode: "0x00000000000000000000000000000000000000aa",
nowSeconds: BigInt(Math.floor(Date.now() / 1000)),
});
if (elsewhere.valid) throw new Error("a payment aimed at another node must be refused");
await stream.revoke();
await budget.close();
const session = await budget.aggregate();
if (!session.reconciled) throw new Error("engine and settlement layer disagree");
For buyers, x402.x402Fetch(stream, fetch) wraps any fetch: on a 402 it answers the challenge from the stream and retries ONCE; a second 402 propagates - fail closed, no payment loops. The one exception is a gateway that has not synced the stream yet: it refuses an allowance payment with headroom unknown: … and a Retry-After header, and starts that sync. x402Fetch waits for the Retry-After time once (at most 10 seconds) and sends the same payment once more.
An exact payment is paid before the seller serves. If the seller refuses it or its upstream fails, the bill is not reversed; the remedy is to re-present the same paid receipt, which the seller serves once for that sale until the receipt expires. x402Fetch keeps the paid receipt of a request that was not served and re-presents it on the next call to the same request, instead of paying a new challenge. Once the seller answers that it is spent (replay: requestRef already consumed after a serve, receipt expired after its window), the next call pays a new challenge.
Migrating from 3.x
@dynamoprotocol/sdk 4.0.0 changes the exact scheme only; the allowance scheme is unchanged. A 3.x exact receipt was signed by a key the seller could not pin, so 4.0.0 accepts only receipts the engine signed for one sale, from signers you pin. There is no setting that accepts the old receipts.
Sellers. The 3.x config (-) against the 4.0.0 config (+): add the receipt trust list, the resource you sell and a replay store. The round trip above runs the 4.0.0 config.
const verified = await x402.verifyPayment(header, {
expectedSigner: engineSigner,
+ trustedReceiptSigners: [{ address: engineSigner }],
serviceNode: seller,
nowSeconds,
+ expectedResource: "https://api.example.test/report",
expectedRequestRef: "req-docs-1",
requiredUnits: 250_000n,
+ isRefConsumed: (ref) => consumed.has(ref),
});
+if (verified.valid && verified.scheme === "exact") consumed.add(verified.requestRef);
Without trustedReceiptSigners, expectedResource, requiredUnits, expectedRequestRef (or isIssuedRef) or isRefConsumed, every exact payment is refused, and verified.missingSetting names the one that is missing. A trustedReceiptSigners entry may carry notBefore and notAfter (unix seconds) for key rotation.
Buyers. No code change: x402.answerChallenge and x402Fetch now ask the core for the receipt (stream.saleReceipt), which needs owner-api 1.9.0. Against an older core they throw UnsupportedByServer naming 1.9.0.
Merchant protection
The seller-side checks are not optional garnish; they are the conformance suite's A.2b section: request-bound payment proofs, replay rejection, idempotent consume records, fail-closed delivery on any verification gap, voucher monotonicity, exposure bounds (refuse new unsettled work past a bound - a free pre-check), and finality-aware access for high prices.
The conformance suite
"Conformance-tested" is a specific, runnable claim (R4). From a clone of the repository:
cd "$DYNAMO_REPO"
pwd
make conformance
It runs the full catalog of thirteen checks - challenge shape and nonce freshness, both schemes, a forged-receipt check, credential revocation, A.2b merchant protection - against the reference seller, funding its test streams in Control Mode, and writes a machine-readable report under packages/x402-conformance/report/, so a sign-off can be pinned and re-checked. The same catalog is packaged as a standalone kit for any endpoint that speaks 402 + X-PAYMENT; it is not published in this release. The gateway plugins pass the identical catalog live (make conformance-kong, make conformance-apisix; Docker required).