x402-refund-hold

npm install x402-refund-hold

The problem

x402's exact scheme is pay-then-serve. By the time your handler runs, the USDC has already moved. So what happens when the thing you just sold doesn't materialise — no availability, upstream 500, the flow timed out?

Returning 409 Sorry is not an answer: you took the money. And the caller is an autonomous agent, so it needs proof of the refund in the response, not an email to a human three days later.

refundHold() makes that the default. One line of middleware and every paid request resolves to exactly one signed artifact — a captured hold with your confirmation attached, or a refund record the customer can verify.

Pricing

Quickstart

import express from "express";
import { paywall, refundHold, executorFromEnv } from "x402-refund-hold";

const app = express();
app.use(express.json());

// 1. Dual-rail paywall — the 402 offers Base *and* Solana; the client picks.
app.use(paywall({ "POST /book": "$0.01" }, { service: "my-merchant" }));

// 2. Refundable holds on top.
const holds = refundHold({ executor: executorFromEnv() });

app.post("/book", holds, async (req, res) => {
  const booking = await tryToBook(req.body);
  if (booking) {
    res.json({ outcome: "confirmed", booking, hold: req.hold!.capture({ artifact: booking }) });
  } else {
    res.json({ outcome: "refunded", refund: await req.hold!.refund("no availability") });
  }
});

The flow

Both terminal states are 200. The refund path is not an error path — it is the artifact you paid for when the booking could not happen.

Both rails, always

Refunds return on the rail the payment arrived on — hold.rail records which one, and createDualRailRefundExecutor routes accordingly. On Solana the facilitator sponsors the network fee, so payers need only USDC and no SOL.

Docs