@tuppence/http402
v0.1.1
Published
Put a price on an API route or an MCP tool: HTTP 402 with Tuppence receipts, verified offline.
Readme
@tuppence/http402
Put a price on an API route in one line, and let people and agents pay for it.
import { Tuppence } from "@tuppence/node";
import { http402 } from "@tuppence/http402";
const tuppence = new Tuppence(process.env.TUPPENCE_SECRET_KEY!);
app.get(
"/v1/report",
http402({ tuppence, price: 50, currency: "gbp", account: "acct_…" }),
(req, res) => res.json(buildReport()),
);What the caller sees
An unpaid request gets 402 Payment Required:
{
"error": { "type": "payment_required", "code": "payment_required", "message": "…" },
"price": 50,
"currency": "gbp",
"resource": "GET /v1/report",
"payment_id": "pay_…",
"accepts": [{ "type": "card_link", "url": "https://pay.tuppence.ai/pay/pay_…#…" }],
"receipt": {
"url": "https://api.tuppence.ai/public/payments/pay_…",
"header": "Tuppence-Client-Secret",
"client_secret": "…"
}
}with a Link: <…>; rel="payment" header. The caller pays at the URL, fetches receipt.url
with the Tuppence-Client-Secret header, and retries with
Authorization: Tuppence-Receipt <receipt_token>and gets the resource. A caller who retries before paying gets the same payment, not a new one each time.
Why it is safe
- Verified offline. The receipt is a JWT signed by Tuppence (EdDSA); it is checked against
Tuppence's published keys (
/.well-known/jwks.json, cached). No call to Tuppence on the hot path. - Bound to what was bought. The receipt names its
resource(defaultMETHOD /path) and amount: a 1p receipt for another route opens nothing here. - Used once. Its
jtiis remembered until it expires (fifteen minutes). The default store is in memory. Running more than one process? Pass a sharedstore({ claim(jti, expiresAt) }, e.g. RedisSET NX EX). - Paid to you. Pass
accountand receipts paid to anyone else are refused.
Credits: agents paying from prepaid balance (no card per call)
Give the route a meter priced the same, and your customers' agents can pay from their prepaid credit instead of a card:
app.get("/v1/report", http402({ tuppence, price: 50, currency: "gbp", credits: { meter: "report" } }), handler);Your server mints the agent a token for its customer, capped and short-lived:
const { token } = await tuppence.request("POST", `/v1/credits/${customerId}/tokens`, {
body: { max_amount: 1000, expires_in: 3600 },
});and the agent sends Authorization: Tuppence-Credits <token> (with an Idempotency-Key, so a
retried request is one use, not two). Tuppence enforces the cap and the expiry as it draws the
credit; past either, the agent gets a 402 saying why (credit_token_limit,
credit_token_expired, insufficient_credits with a topup_url).
Other frameworks
// Next.js route handlers, Hono, Bun, Deno, Workers
export const GET = withPayment({ tuppence, price: 50, currency: "gbp" }, async (req, paid) =>
Response.json(await buildReport()),
);
// An MCP tool: an optional `receipt` argument; without it the agent is told where to pay
server.tool(
"deep_research",
{ topic: z.string(), receipt: z.string().optional() },
paidTool({ tuppence, price: 200, currency: "gbp", name: "deep_research" }, async ({ topic }) => ({
content: [{ type: "text", text: await research(topic) }],
})),
);
// Anything else: the framework-free core
const decide = payWall({ tuppence, price: 50, currency: "gbp" });
const decision = await decide({ method, path, authorization, caller });