X402 Payment

TIP

For full x402 protocol documentation — including payment schemes, payload formats, and facilitator details — see the x402 Protocol section.

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 the current temperature in San Francisco from this paid API:
https://router.fluxapay.xyz/api/open-meteo/v1/forecast?latitude=37.77&longitude=-122.42&current=temperature_2m

** 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 instructions in the
response.

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 on weather
        API calls over the next 30 days.",
      "category": "weather_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": "<payTo from the 402 response>",
    "host": "router.fluxapay.xyz",
    "resource": "https://router.fluxapay.xyz/api/open-meteo",
    "description": "API access: /v1/forecast",
    "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.

With the CLI

If your agent can run shell commands, the FluxA Wallet CLI handles credentials, JWT refresh and the payload fields for you:

fluxa-wallet mandates                                   # reuse a signed mandate if one fits
fluxa-wallet mandate-create --desc "Up to 0.10 USDC for weather API calls, 30 days" \
  --amount 100000 --seconds 2592000                     # user signs authorizationUrl
fluxa-wallet mandate-status --id <mandateId>            # ready when "signed"
fluxa-wallet x402 --mandate <mandateId> --payload '<full 402 response>'
# retry the request with data.xPaymentB64 as the X-Payment header

Pass the complete 402 response as --payload. The CLI supports both x402 v1 and v2 payloads.