request_x402_payment — pay an x402 bill on behalf of the user

Available via MCP and HTTP API.

• MCP: call request_x402_payment with the parsed 402 payload and an intent description.
• HTTP: call POST /api/payment/x402V1Payment (see X402 payment endpoint)

---

Purpose
Signs and submits an x402 “exact” (EIP‑3009) payment using FluxA, then returns a payload the agent can attach to the original HTTP request (for example as an X-Payment header).

What it does

• Accepts the parsed 402 Payment Required payload (payment_required) plus a description of the agent’s intent.
• Selects a suitable payment option from accepts (currently supports the "exact" scheme).
• Ensures the Agent ID is registered and that the jwt is valid (refreshing it if necessary).
• Calls the FluxA Wallet API to create an EIP‑3009 payment authorization, respecting the user’s policies and wallet balance.
• Records an audit entry and returns the wallet’s response (typically a payment authorization object or error details).

Typical agent usage

1. Call a remote API. If the response is HTTP 402 with x402 metadata, parse it into the shape expected by payment_required.
2. Call request_x402_payment with:
   • the full payment_required object,
   • an intent block describing what you’re trying to do (for audit / UX), and
   • optional options like validity_window_seconds or preferences.
3. If successful, construct an X-Payment (or equivalent) header from the returned payload and retry the original request.
4. If it fails, surface the pmc.instructions guidance to the user or logs.

Key inputs

• payment_required — the structured representation of the x402 challenge (includes accepts[], network, asset, maxAmountRequired, resource, description, etc.).
• selection (optional) — hints for which accepts entry to use (index, scheme, network, asset).
• intent — why the call is being made (e.g., "why": "Fetch paid WHOIS data for fluxapay.xyz" plus HTTP method, URL, and caller).
• options (optional) — e.g., validity_window_seconds, preferred_network, preferred_asset, approval_id.

Common failures and remedies

• need_approval — Show the approvalUrl to the user and retry with approval_id once approved.
• policy_denied — Exceeded limits; guide the user to adjust policy limits or wait for reset.
• need_manual_signature — Risk control requires a wallet signature; surface the approvalUrl.
• approval_expired / approval_used — Re‑initiate approval and retry with the new approval_id.
• agent_not_authorized / no_signer — Ask the user to re‑authorize the agent.