anchor-x402-safe-pay
Screen a recipient before your agent sends funds. A one-line, wallet-agnostic wrapper that runs an anchor-x402 risk pre-flight (allow / review / block) on the counterparty and only lets the payment through if it's clean.
It wraps the payment your agent already makes — you don't call a new "service", you decorate your send. Works with viem, ethers, x402-fetch, a Solana signer, anything: you pass your own send as a thunk.
Why
Autonomous agents move USDC without a human watching the recipient. safe-pay puts a sanctions + address-reputation check (drainer / phishing / mixer) in the send path, so a payment to a flagged address fails closed instead of draining a wallet.
Install
npm install anchor-x402-safe-pay # or: pip install anchor-x402-safe-pay
Wiring it into an agent (or letting a coding assistant do it)? llms.txt is a machine-readable integration index — API, verdict semantics, and the one-line hook snippet per x402 client.
Use — JavaScript / TypeScript
import { guardedSend } from "anchor-x402-safe-pay";
// `paidFetch` is your x402-capable fetch (e.g. from @x402/fetch's
// wrapFetchWithPayment) — it settles the $0.02 screen call for you.
await guardedSend(
recipient,
() => wallet.sendUsdc(recipient, amount), // your real send, runs only if allowed
{ fetchImpl: paidFetch },
);
If the recipient is flagged, guardedSend throws ScreenBlockedError (carrying the full verdict) and your send never runs.
See it fail closed — a real $0.02 screen refusing a live OFAC-SDN Tornado Cash address:
Run it yourself: examples/block-sanctioned.mjs — node examples/block-sanctioned.mjs (no wallet needed for the free simulation; set PRIVATE_KEY for the live check above).
Use — Python
from anchor_safe_pay import guarded_send
# `paid_post(url, json_body) -> dict` is your x402-capable POST (pays the $0.02).
guarded_send(
recipient,
lambda: wallet.send_usdc(recipient, amount), # runs only if allowed
fetch=paid_post,
)
Register on your client's existing pre-pay hook
Most x402 clients already expose a hook that fires with the recipient (payTo) before signing — you don't need the wrapper, just a decision. screenAllows() is that decision (never throws; folds blockOn/onError so the hook stays a one-liner). Full snippets in examples/:
Official @x402 client (beforePaymentCreation):
x402Client.onBeforePaymentCreation(async (req) => {
const { ok, verdict } = await screenAllows(req.payTo, { fetchImpl: paidFetch });
return ok ? undefined : { abort: true, reason: verdict.recommendation };
});
elizaOS plugin-wallet (onBeforePayment → return false to block):
const onBeforePayment = async (req) => (await screenAllows(req.payTo, { fetchImpl: paidFetch })).ok;
faremeter (payerChooser → throw to abort), qntx/r402 (before_payment_creation), and the Python client (on_before_payment_creation) take the same shape — see examples/. Use paidFetch other than the client you're guarding, so screening a payment never recurses.
Add a per-send amount cap (at the hook)
Screening answers who the recipient is; it doesn't bound how much. With x402 the amount is payee-set in the 402 challenge, so a cap checked when the agent plans a call can be bypassed by a challenge-time bump — a TOCTOU. composeCapWithScreen folds the recipient verdict and a stateless per-send cap into one fail-closed decision, evaluated at the pre-payment hook against the real challenge amount (the seat that carries both payTo and amount — e.g. agentkit's beforePayment):
import { composeCapWithScreen } from "anchor-x402-safe-pay";
const beforePayment = composeCapWithScreen({ maxAmount: 1_000_000n, fetchImpl: paidFetch }); // 1 USDC, atomic units
const { abort, reason } = await beforePayment({ payTo, amount }); // reason: "flagged_recipient" | "exceeds_cap"
Stateless by design — a flagged recipient, an over-cap amount, or a screen failure all fail closed; maxAmount is inclusive (paying exactly the cap is allowed). Cumulative / rate budgets are deliberately out of scope: those need state and belong in the wallet/agent layer. Python: compose_cap_with_screen(max_amount=…, fetch=…) returns hook(pay_to, amount) -> dict.
Verdict → action
/v1/screen returns a recommendation you branch on:
| recommendation | meaning | default |
|---|---|---|
allow |
clean | send runs |
review |
needs a human (elevated risk) | held (fail-closed) |
block |
sanctioned / drainer / phishing | held |
Only allow, review, and block are accepted as valid screening recommendations. Unknown or malformed recommendations are handled through onError / on_error and therefore block by default.
By default blockOn: ["block", "review"] — a review holds. To send on review (e.g. you have your own human-in-the-loop), set blockOn: ["block"] and inspect the thrown verdict:
try {
await guardedSend(recipient, send, { blockOn: ["block"], fetchImpl: paidFetch });
} catch (e) {
if (e.verdict.recommendation === "review") await askAHuman(e.verdict);
else throw e; // hard block
}
Options
fetchImpl(JS) /fetch(Py) — required for real use: your x402-capable fetch/POST, so the$0.02screen call settles. Without it you'll get a 402.blockOn— recommendations that refuse the send. Default["block", "review"].onError— what to do if the screen call itself fails (network / 402 / anchor down):"block"(default — a safety guard fails safe) or"allow"(anchor downtime never blocks your payments). Choose deliberately.timeoutMs/timeout,endpoint— overridable.
Need the raw verdict without the send? Call screen(address, { fetchImpl }) directly.
Cost
Each guarded send makes one $0.02 USDC /v1/screen call on Base — cheap insurance against a drained payment. The screen degrades to a partial verdict rather than erroring if the reputation layer is briefly unavailable.
MIT.
Metadata
Release files for anchor-x402-safe-pay 0.3.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| anchor_x402_safe_pay-0.3.0.tar.gz | 78.7 kB | With provenance | Details for anchor_x402_safe_pay-0.3.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| anchor_x402_safe_pay-0.3.0-py3-none-any.whl | Python 3 | none | any | Details for anchor_x402_safe_pay-0.3.0-py3-none-any.whl |
Total release size: 86.0 kB
Release files / anchor_x402_safe_pay-0.3.0.tar.gz
| Download URL | anchor_x402_safe_pay-0.3.0.tar.gz |
|---|---|
| Size | 78.7 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
84e88b743196873048734a3d8f75a14be987591290d879438de73f9132c911e9
|
|
BLAKE2b-256 checksum How to use checksums |
64784e8dc3912e2f2e80767b6cdf2a524d9b01ecb61b9cf0fc731c472d8fdbb6
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Aug 22, 2026.
Transparency logRelease files / anchor_x402_safe_pay-0.3.0-py3-none-any.whl
| Download URL | anchor_x402_safe_pay-0.3.0-py3-none-any.whl |
|---|---|
| Size | 7.2 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
d1621e540d341c94ea1f4772d16e2760914793aa5eb63b9e01e70d4d7ca39d39
|
|
BLAKE2b-256 checksum How to use checksums |
ad895a8bd566bb61661abc47ca3bdf4a91123eb4de4e3c8f30505434fbecdee1
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Aug 22, 2026.
Transparency logSecurity for anchor-x402-safe-pay 0.3.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
Both files in this release have been uploaded with provenance metadata.
Attestation for anchor_x402_safe_pay-0.3.0.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Aug 22, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.