@factline/x402-pay-guard
v0.2.2
Published
Check every x402 payment before your agent signs it: OFAC screening of the payTo wallet, seller history and uptime, price sanity. One line on any x402Client.
Maintainers
Readme
@factline/x402-pay-guard
Check who your agent is paying before it signs an x402 payment. One line on any x402Client.
The x402 SDK's spend controls cap how much your agent pays. This guard checks to whom. Before each payment it asks Factline's free pay guard:
- Is payTo the seller's wallet? Factline records the payTo wallets every seller lists in the Coinbase x402 Bazaar and the Circle x402 catalogue. A known seller asking to be paid at a wallet it never listed (a swapped or prompt-injected payTo) gets
review, ordenyin strict mode. - Is payTo sanctioned? Exact match against the US OFAC list of digital currency addresses.
- Is the seller real? Paying wallets and calls in the last 30 days, payers left after removing self-payments, when it was first listed, and Factline's nightly uptime probes. Unknown sellers get a domain age check.
- Is the price sane? The amount against the seller's lowest listed price and your budget.
It answers allow, review or deny, with reasons, the sanctions list version, a timestamp and an Ed25519-signed verdict you can keep with the payment as proof of the check. Answers are cached per seller, wallet and amount for 10 minutes, so the guard adds one fast call per new seller and price, not per payment.
Install
npm install @factline/x402-pay-guardUse
import { wrapFetchWithPayment, x402Client } from "@x402/fetch";
import { ExactEvmScheme } from "@x402/evm";
import { withPayGuard } from "@factline/x402-pay-guard";
const client = withPayGuard(
new x402Client().register("eip155:8453", new ExactEvmScheme(signer)),
{ mode: "strict", maxUsd: 1 },
);
const fetchWithPay = wrapFetchWithPayment(fetch, client);Strict mode (recommended for agents that run unattended) fails closed, in line with the OWASP cheat sheet for AI agent payments: a payTo the seller does not list is denied, review blocks the payment, and if the guard cannot be reached the payment is aborted. Standard mode (the default) only blocks on deny.
Options: mode ("standard" or "strict"), maxUsd (budget per payment, above it is denied), onReview ("allow", "block" or a callback), failOpen (pay when the guard is unreachable; default true, false in strict mode), apiKey (a Factline key gets its own rate limit), onDecision (log every answer, including the signed verdict).
For SDKs that take a hook rather than a client (for example a beforePayment option): client.onBeforePaymentCreation(payGuardHook({ mode: "strict" })).
Without the hook, call it yourself:
import { checkPayment } from "@factline/x402-pay-guard";
const answer = await checkPayment({ url, payTo, amountUsd: 0.05, mode: "strict" });
if (answer.decision !== "allow") throw new Error(answer.reasons[0]);Or plain HTTP: GET https://factline.dev/v1/pay/guard?url=...&pay_to=...&amount_usd=0.05&mode=strict. MCP tool: x402_pay_guard on https://factline.dev/mcp/kyc.
Verifying a verdict
answer.verdict.signed_payload is a JSON string with the decision, seller origin, payTo, amount, mode, list version and time. answer.verdict.signature is an Ed25519 signature (base64url) over that exact string, with the public key at https://factline.dev/.well-known/factline-receipts.json.
Agent kits
- Coinbase AgentKit (x402 action provider): wrap the
x402Clientthe provider builds withwithPayGuardbefore it is passed to the fetch wrapper. - ElizaOS (x402 plugin): same, at the point where the plugin creates its payment client; expose
modeandmaxUsdas character settings. - GOAT SDK: add the guard to the x402 plugin's client, or call
checkPaymentin a tool before the paid request.
See also
- x402 Seller Health Index: every seller, its listed wallets, payers and nightly uptime.
- x402 Facilitator Health: hourly checks of the public facilitators.
Limits
Exact-match OFAC wallet screening, catalogue wallet matching and public seller signals, not blockchain analytics or a guarantee. A seller that is in neither catalogue has no listed wallets to compare with (known_for_seller: null). Rate limit: 30 checks a minute per IP; a Factline API key gets its own bucket. Free.
MIT licence. Made by Factline.
