Mandates

Create and query payment mandates — pre-authorized spending budgets that let agents pay without per-transaction user approval.

All endpoints require Authorization: Bearer <agent-jwt>.

---

Create intent mandate

Create an intent mandate draft. If the agent is already authorized, the mandate moves straight to pending_signature; otherwise the response includes an authorizationUrl for user onboarding.

curl -X POST https://walletapi.fluxapay.xyz/api/mandates/create-intent \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $JWT_TOKEN" \
  -d '{
    "intent": {
      "naturalLanguage": "Pay for WHOIS API calls",
      "currency": "USDC",
      "limitAmount": "5000000",
      "validForSeconds": 2592000,
      "category": "api-usage",
      "hostAllowlist": ["x402whois.com"]
    }
  }'

Key fields:

• naturalLanguage — human-readable description of the mandate's purpose (required).
• currency — only USDC is supported (optional, defaults to USDC).
• limitAmount — total spending cap in atomic units (required, 6 decimals; 5000000 = 5.0 USDC).
• validForSeconds — how long the mandate stays active (required, max 1 year).
• category — optional label for grouping mandates.
• hostAllowlist — optional list of hosts this mandate may pay. Omit for any host.

Response (agent authorized):

{
  "status": "ok",
  "mandateId": "mnd_abc12345",
  "authorizationUrl": "https://agentwallet.fluxapay.xyz/mandate/mnd_abc12345",
  "expiresAt": "2025-02-28T00:00:00.000Z",
  "agentStatus": "ready"
}

Response (agent not yet authorized):

{
  "status": "ok",
  "mandateId": "mnd_abc12345",
  "authorizationUrl": "https://agentwallet.fluxapay.xyz/onboard/...",
  "expiresAt": "2025-02-28T00:00:00.000Z",
  "agentStatus": "needs_wallet_authorization"
}

Surface the authorizationUrl so the user can sign the mandate in their browser.

---

Get eligible mandates

Find mandates that can cover a specific payment. Use this before calling the X402 V3 payment endpoint to pick the right mandateId.

curl -G https://walletapi.fluxapay.xyz/api/mandates/eligible \
  -H "Authorization: Bearer $JWT_TOKEN" \
  --data-urlencode "host=x402whois.com" \
  --data-urlencode "amount=10000" \
  --data-urlencode "currency=USDC"

Query parameters:

• host — the host being paid (required).
• amount — payment amount in atomic units (required).
• currency — USDC (optional, defaults to USDC).

Response:

{
  "status": "ok",
  "criteria": {
    "host": "x402whois.com",
    "amount": "10000",
    "currency": "USDC"
  },
  "eligibleMandates": [
    {
      "mandateId": "mnd_abc12345",
      "status": "signed",
      "isEnabled": true,
      "naturalLanguage": "Pay for WHOIS API calls",
      "category": "api-usage",
      "currency": "USDC",
      "limitAmount": "5000000",
      "spentAmount": "100000",
      "pendingSpentAmount": "0",
      "remainingAmount": "4900000",
      "validFrom": "2025-01-01T00:00:00.000Z",
      "validUntil": "2025-02-28T00:00:00.000Z",
      "hostAllowlist": ["x402whois.com"],
      "mandateHash": "0x...",
      "signedAt": "2025-01-01T12:00:00.000Z",
      "createdAt": "2025-01-01T11:00:00.000Z",
      "detailsUrl": "https://agentwallet.fluxapay.xyz/mandate/mnd_abc12345",
      "signUrl": "https://agentwallet.fluxapay.xyz/mandate/mnd_abc12345"
    }
  ]
}

An empty eligibleMandates array means no mandate covers this payment — fall back to X402 V1 or create a new mandate first.

---

List agent mandates

Retrieve all intent mandates for the current agent.

curl https://walletapi.fluxapay.xyz/api/mandates \
  -H "Authorization: Bearer $JWT_TOKEN"

Response:

{
  "status": "ok",
  "mandates": [
    {
      "mandateId": "mnd_abc12345",
      "status": "signed",
      "isEnabled": true,
      "naturalLanguage": "Pay for WHOIS API calls",
      "category": "api-usage",
      "currency": "USDC",
      "limitAmount": "5000000",
      "spentAmount": "100000",
      "pendingSpentAmount": "0",
      "remainingAmount": "4900000",
      "validFrom": "2025-01-01T00:00:00.000Z",
      "validUntil": "2025-02-28T00:00:00.000Z",
      "hostAllowlist": ["x402whois.com"],
      "mandateHash": "0x...",
      "signedAt": "2025-01-01T12:00:00.000Z",
      "createdAt": "2025-01-01T11:00:00.000Z"
    }
  ]
}

---

Get mandate by ID

Get details for a specific mandate, including real-time remaining budget.

curl https://walletapi.fluxapay.xyz/api/mandates/agent/mnd_abc12345 \
  -H "Authorization: Bearer $JWT_TOKEN"

Response: same shape as a single item in the list above.