Screen x402 payment metadata for PII before signing the payment.

Call BEFORE sending the payment request. Detects emails, phone numbers, SSNs, names, and other PII in the resource URL, description, and reason fields and returns redacted strings plus per-field entity counts.

No side effects.

Runs in one of two modes:

• in_process (default): wraps the local presidio_x402 PIIFilter.

• remote: when both PRESIDIO_X402_MCP_REMOTE_BASE_URL and ..._REMOTE_API_KEY are set, POSTs to /v1/screen on that host for centralized audit. On remote failure, returns a structured error dict instead of silently falling back — the caller must decide whether to retry, accept reduced screening, or abort.

Args: resource_url: x402 resource URL the agent is about to pay (max 2048 chars). description: Human-readable description (max 4096 chars). reason: Reason / memo string (max 4096 chars). entities: Optional whitelist of Presidio entity types to detect. If None, all configured entities are scanned.

Returns: On success: dict with keys redacted_resource_url, redacted_description, redacted_reason, entities_found (list of {entity_type, field, count}), and mode (one of "in_process", "remote"). On remote failure: dict with keys error (one of "auth_error", "rate_limit", "unavailable"), detail, optional retry_after (for rate_limit), and mode ("remote").

Check whether a payment is allowed by the configured spending policy.

WARNING: this records the spend against rolling time-window ledgers. Call exactly once, immediately before submitting the payment. If you call this and then do not pay, the spend window will be inflated until it rolls over.

Configure limits at server startup via PRESIDIO_X402_MCP_* env vars.

Args: resource_url: x402 resource URL being paid (used for per-endpoint limits). amount_usd: Payment amount in USD-equivalent.

Returns: {"allowed": true} on success, or {"allowed": false, "reason": str, "limit_usd": float, "amount_usd": float}.

Check whether this exact payment has been seen recently (replay protection).

WARNING: this records the fingerprint. Call exactly once, immediately before submitting the payment.

Cross-process detection requires PRESIDIO_X402_FINGERPRINT_KEY (and optionally PRESIDIO_X402_MCP_REDIS_URL); otherwise each MCP server process has its own ephemeral in-memory store.

Args: resource_url: x402 resource URL. pay_to: Recipient address. amount: Amount as string (preserves precision). currency: Currency symbol (e.g. "USDC"). deadline_seconds: Payment deadline as epoch seconds.

Returns: {"is_replay": false, "fingerprint": ""} on first seen, or {"is_replay": true, "fingerprint": ""} on duplicate.