X402 V3 payment endpoint

Authorize an x402 payment using a signed mandate. Unlike V1 (which may require per-transaction user approval), V3 deducts from a pre-authorized mandate budget automatically.

---

Prerequisites

1. The agent has a signed, enabled mandate that covers the target host and amount. Use GET /api/mandates/eligible to find one.
2. The mandate must have sufficient remaining budget.

---

Request

curl -X POST https://walletapi.fluxapay.xyz/api/payment/x402V3Payment \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $JWT_TOKEN" \
  -d '{
    "mandateId": "mnd_abc12345",
    "scheme": "exact",
    "network": "base",
    "amount": "10000",
    "currency": "USDC",
    "assetAddress": "0x833589fCD6Edb6E08f4c7C32D4f71b54bdA02913",
    "payTo": "0xfA0eE7B2F13D80680F31771abc93D06a2C749150",
    "host": "x402whois.com",
    "resource": "https://x402whois.com/api/v1/whois?domain=fluxapay.xyz",
    "description": "WHOIS lookup for fluxapay.xyz",
    "tokenName": "USD Coin",
    "tokenVersion": "2",
    "validityWindowSeconds": 60
  }'

All fields are the same as V1, plus:

• mandateId — ID of the signed mandate to debit (required).

---

Response (success)

{
  "status": "ok",
  "xPaymentB64": "<base64-encoded-xPayment>",
  "xPayment": {
    "x402Version": 1,
    "scheme": "exact",
    "network": "base",
    "payload": {
      "signature": "0x...",
      "authorization": {
        "from": "0x...",
        "to": "0x...",
        "value": "10000",
        "validAfter": 1700000000,
        "validBefore": 1700000060,
        "nonce": "0x..."
      }
    }
  },
  "paymentRecordId": "...",
  "expiresAt": 1700000060,
  "payment_model_context": { /* LLM guidance */ }
}

Attach xPaymentB64 as the X-Payment header when retrying the original API call — same as V1.

---

Error responses

Code	status	Meaning
400	mandate_required	mandateId was not provided
403	mandate_not_found	Mandate does not exist or does not belong to this agent
403	mandate_insufficient_budget	Remaining mandate budget is less than the payment amount
403	agent_not_authorized	Agent is not authorized in the user's wallet
403	policy_denied	Policy check failed

All error responses include payment_model_context with remediation hints for LLM agents.

---

Typical flow

1. Receive HTTP 402 from a resource.
2. Call GET /api/mandates/eligible?host=...&amount=... to find a matching mandate.
3. If found, call POST /api/payment/x402V3Payment with the mandateId.
4. Attach the returned xPaymentB64 as X-Payment and retry.
5. If no eligible mandate exists, fall back to V1 or create a new mandate.