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"); plus decision_ref when signed decision evidence is enabled (pass it to the gates as prior_decision_refs). 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. Screened first; only the redacted URL reaches the policy engine (per-endpoint limits match on it, so keep PII out of configured endpoint prefixes). amount_usd: Payment amount in USD-equivalent. prior_decision_refs: Optional decision_ref values this server returned earlier for the same payment (e.g. from screen_payment_metadata); linked into the signed record. Max 8.

Returns: {"allowed": true} on success, or {"allowed": false, "reason": str, "limit_usd": float, "amount_usd": float}; plus decision_ref when signed decision evidence is enabled.

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. prior_decision_refs: Optional decision_ref values this server returned earlier for the same payment; linked into the signed record. Max 8.

Returns: {"is_replay": false, "fingerprint": ""} on first seen, or {"is_replay": true, "fingerprint": ""} on duplicate; plus decision_ref when signed decision evidence is enabled.