Skip to content
Crifine
DocumentationAPI referencePackagesChangelog

@crifine/x402

A fetch wrapper for 402 Payment Required, with spend limits that are not optional.

npm install @crifine/x402

Works with any API that speaks x402 — it has no dependency on the rest of Crifine.

import { x402Fetch, usdcSettler } from "@crifine/x402";

const pay = x402Fetch({
  maxPerCall: 0.01,               // required
  maxTotal: 5,                    // lifetime budget for this wrapper
  allowHosts: ["api.crifine.app"],
  onPayment: (event) => audit(event),
  settle: usdcSettler({ walletClient }),
});

pay.spent;      // running total
pay.remaining;  // budget left, or Infinity
pay.receipts;   // every settlement, in order — an audit trail with no wiring

Why payments are serialised by default

With parallel calls, two 402s can both read the budget before either has spent, and the pair sails past a limit each of them individually respected. An unattended agent fanning out ten requests would blow through maxTotal without a single check failing. concurrency defaults to 1; raise it only if you can tolerate that.

Errors

ErrorMeaningWhat an agent should do
SpendLimitErrorQuote above maxPerCallSkip, or widen the limit deliberately
BudgetExhaustedErrormaxTotal reachedStop — a budget is a decision, not a hiccup
HostNotAllowedError402 from an unlisted hostTreat as hostile; something redirected you
MalformedTermsError402 without readable termsThe server is broken; do not pay

Nothing is spent when any of these throw — the ledger only moves on a receipt, and it moves by the *receipt* amount, not the quoted one.