X402 Payment

What it is

X402 Payment is FluxA's implementation of the HTTP 402 payment protocol. When an API responds with HTTP 402 (Payment Required), the agent uses FluxA to authorize a USDC payment on Base, receives a signed payment proof, and retries the original request with the proof attached.

FluxA supports two versions:

• V1 — each payment may require user approval in real time.
• V3 (recommended) — payments deduct from a pre-signed intent mandate, enabling fully autonomous spending within the user's budget.

What agents can do with it

• Pay for APIs automatically — access any x402-enabled API without manual intervention (V3 with mandate).
• Handle 402 responses — detect payment requirements, authorize payment, and retry seamlessly.
• Budget-controlled spending — the user sets a total budget and validity window via the mandate; the agent spends within those limits.
• Multi-call sessions — a single mandate can cover many individual API calls until the budget runs out.

Related APIs

Method	Endpoint	Description
POST	/api/mandates/create-intent	Create a spending mandate (budget + time window)
GET	/api/mandates/eligible	Find mandates that cover a specific payment
POST	/api/payment/x402V3Payment	Pay using a signed mandate (V3, recommended)
POST	/api/payment/x402V1Payment	Pay with per-transaction approval (V1, fallback)

Integration flow

Below is an example prompt you can give an AI agent to pay for an x402 API using the V3 mandate flow.

** Your task **
Get Polymarket trading recommendations for the last hour based
on news trends and onchain smart money signals from this API:
https://fluxa-x402-api.gmlgtm.workers.dev/polymarket_recommendations_last_1h

** User intent (spend plan) **
I want you to complete this task end-to-end. My total budget is
0.10 USDC and it should be valid for 30 days starting now.
If an intent mandate is required, use this intent to create the
mandate (budget + time window), then have me review and sign it
in the FluxA Wallet UI.

** Process x402 payment (x402 V3 with intent mandate) **
If the API responds with HTTP 402 or indicates payment is
required, use the FluxA Wallet x402 V3 payment endpoint:
https://walletapi.fluxapay.xyz/api/payment/x402V3Payment

Important:
- x402 V3 requires a user-signed intent mandate (mandateId).
  Payments will NOT succeed without it.
- Create an intent mandate for this task first, then pay using
  the returned mandateId.

** Create a new intent mandate **
If you DO NOT have an Agent JWT yet, call this endpoint anyway
WITHOUT Authorization and follow the returned
payment_model_context instructions.

curl -X POST https://walletapi.fluxapay.xyz/api/mandates/create-intent \
  -H "Content-Type: application/json" \
  -d '{
    "intent": {
      "naturalLanguage": "I plan to spend up to 0.10 USDC to get
        Polymarket trading recommendations valid for 30 days.",
      "category": "trading_data",
      "currency": "USDC",
      "limitAmount": "100000",
      "validForSeconds": 2592000,
      "hostAllowlist": []
    }
  }'

If you already have an Agent JWT, include it as the Authorization
Bearer token. Otherwise, omit Authorization and follow the
returned instructions.

The response returns:
- mandateId
- authorizationUrl (short link, TTL 10 minutes)

Ask me to open authorizationUrl to authorize the agent (if
needed) and sign the mandate. Then proceed to payment with
mandateId.

** x402 V3 payment (agent JWT required) **
curl -X POST https://walletapi.fluxapay.xyz/api/payment/x402V3Payment \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $AGENT_JWT" \
  -d '{
    "mandateId": "<MANDATE_ID_FROM_CREATE_INTENT>",
    "scheme": "exact",
    "network": "base",
    "amount": "10000",
    "currency": "USDC",
    "assetAddress": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
    "payTo": "0xFf319473ba1a09272B37c34717f6993b3F385CD3",
    "host": "fluxa-x402-api.gmlgtm.workers.dev",
    "resource": "https://fluxa-x402-api.gmlgtm.workers.dev/polymarket_recommendations_last_1h",
    "description": "Get Polymarket trading recommendations",
    "tokenName": "USD Coin",
    "tokenVersion": "2",
    "validityWindowSeconds": 60
  }'

When the wallet returns status=ok, use xPaymentB64 as the
"X-Payment" header and retry the merchant request.