@usesaferoute/x402 v0.17.0

Guard, pay, and reconcile Base x402 payments with signed, noncustodial SafeRoute receipts.

npm install @usesaferoute/x402@^0.17.0 @x402/core@^2.21.0

import { guardedX402Fetch } from "@usesaferoute/x402";

const { response, guard, reconciliation } = await guardedX402Fetch(url, {
  payer,
  probeFetch: fetch,
  paymentFetch: x402AwareFetch,
  policy: {
    maxAmountAtomic: "10000000",
    allowedHosts: ["merchant.example"],
  },
});

For a drop-in fetch replacement, create it once:

import { createGuardedX402Fetch } from "@usesaferoute/x402";

const safeX402Fetch = createGuardedX402Fetch({
  payer,
  paymentFetch: x402AwareFetch,
  policy: { maxAmountAtomic: "10000000" },
});

Calls that do not return 402 Payment Required pass through unchanged. Use the optional onResult hook to capture verified guard and reconciliation receipts.

probeFetch performs the unpaid request, obtains SafeRoute's free signed guard, and submits free reconciliation. paymentFetch is used exactly once, against the merchant, and only after the signed decision is ALLOW. SafeRoute then checks the returned payment evidence against the exact mined Base USDC transfer. A pending or mismatched settlement is never marked safe for an automatic retry.

The SDK accepts your existing paymentFetch instead of a wallet or private key. This makes the same integration usable from plain Node.js, Coinbase AgentKit-style wallet runtimes, OpenAI Agents SDK tools, and Vercel AI SDK tools. Copy-paste adapters are documented in the repository's INTEGRATIONS.md.

AutoFund

import { fetchWithSafeRoute } from "@usesaferoute/x402";

const response = await fetchWithSafeRoute(url, {
  payer,
  fundingToken: WETH,
  maximumSellAmount: "10000000000000000",
  postPaymentBuffer: "5000000",
  fetch: x402AwareFetch,
  getUsdcBalance,
  signMessage: wallet.signMessage,
  confirmAndSubmitFunding,
  waitForFundingConfirmation,
  referralCode: "YOUR_PARTNER_CODE",
});

postPaymentBuffer: "5000000" means five Base USDC remains after the payment. The SDK requests payment amount + buffer and enforces SafeRoute's current public cap. Use targetUsdcBalance only when an explicit pre-payment target is required; do not set both fields.

The SDK never receives a private key. The buyer-owned callbacks display, sign, broadcast, and confirm the funding transaction. AutoFund retries the original x402 request once after the signed USDC target is confirmed.

Use createSafeRouteClient(options).proof(input) before signing a Base token, transaction, or trade. Proof receipts are verified against SafeRoute's public Ed25519 key registry by default.

Seller Revenue Recovery

import {
  scanRevenueLeak,
  beginRecoverySubscription,
  activateSellerProduct,
  createRecoveryCloudClient,
} from "@usesaferoute/x402";

const report = await scanRevenueLeak({
  url: "https://seller.example/api/report",
});

const order = await beginRecoverySubscription(
  "starter",
  {
    idempotencyKey: crypto.randomUUID(),
    endpointUrl: "https://seller.example/api/report",
  },
  { fetch: x402AwareFetch },
);

const activated = await activateSellerProduct({
  activationId: order.activation.activationId,
  activationSecret: order.activationSecret,
  transactionHash: minedTransactionHash,
});
const recovery = createRecoveryCloudClient(activated.apiKey);

Paid activation requires both the high-entropy activation secret and the exact mined canonical Base USDC transfer. The SDK never receives a wallet key and SafeRoute never signs or broadcasts a merchant transaction.