Skip to main content

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

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.

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.

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.02 screen 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.2.1

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for anchor-x402-safe-pay 0.2.1
File Size Uploaded Provenance Actions
anchor_x402_safe_pay-0.2.1.tar.gz 10.6 kB With provenance Details for anchor_x402_safe_pay-0.2.1.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for anchor-x402-safe-pay 0.2.1
File Interpreter ABI Platform Actions
anchor_x402_safe_pay-0.2.1-py3-none-any.whl Python 3 none any Details for anchor_x402_safe_pay-0.2.1-py3-none-any.whl

Total release size: 16.5 kB

Release files / anchor_x402_safe_pay-0.2.1.tar.gz

Download URL anchor_x402_safe_pay-0.2.1.tar.gz
Size 10.6 kB
Tags Source
SHA-256 checksum
How to use checksums
aaf1d5448a3eb5637b099e0bfc87be3c636090781c65a3c661e21bd4aefb9953
BLAKE2b-256 checksum
How to use checksums
2935efef58993d30f4021b896fcaa6a997c5be6d32cde8d2a3645985307811d5
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 15, 2026.

Transparency log

Release files / anchor_x402_safe_pay-0.2.1-py3-none-any.whl

Download URL anchor_x402_safe_pay-0.2.1-py3-none-any.whl
Size 5.9 kB
Tags Python 3
SHA-256 checksum
How to use checksums
f8bbc225aec632b9078d4d1a1a5222039d71ecbb346a55556587426ab022da84
BLAKE2b-256 checksum
How to use checksums
619b58187443b1fe936906bd05348b506119e4e25d6ef1f6358580fcdf538a27
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 15, 2026.

Transparency log

Security for anchor-x402-safe-pay 0.2.1

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.

Select from 2 files

Attestation for anchor_x402_safe_pay-0.2.1.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 15, 2026.

Transparency log

A 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.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page