AI Agent Guide

This guide walks you through integrating an AI agent with FluxA Wallet — from registration to autonomous payments, payouts, and revenue collection.

How it works

Register Agent ID → Get user authorization → Use wallet capabilities

1. Register an Agent ID — call the /register endpoint to obtain agent_id, token, and jwt. These credentials identify your agent in every subsequent API call.

2. Get user authorization — the user opens the authorizationUrl returned by FluxA to grant your agent access to their wallet. Until authorized, payment and payout calls will be rejected.

3. Use wallet capabilities — once authorized, the agent can:

Capability	What it does	Guide
X402 Payment	Pay for x402-enabled APIs automatically using intent mandates	X402 Payment
Payout	Send USDC to any external address on Base	Payout
Payment Link	Create shareable links to collect USDC payments	Payment Link
Unify Payment Link (UPL)	Send USDC to any agent using only their Agent ID	UPL

Quick start

Step 1 — Register

curl -X POST https://agentid.fluxapay.xyz/register \
  -H "Content-Type: application/json" \
  -d '{
    "agent_name": "My Agent",
    "client_info": "my-app-v1"
  }'

Store the returned agent_id, token, and jwt securely. See Agent ID for details.

Step 2 — Get user authorization

When the agent first calls a payment or mandate endpoint, the response includes an authorizationUrl if the agent is not yet authorized. Present this URL to the user — they open it in a browser to grant wallet access.

Step 3 — Start using the wallet

With a valid JWT and user authorization in place, the agent can:

• Pay for APIs — create an intent mandate, have the user sign it, then call x402V3Payment with the mandateId to pay automatically within the approved budget. See X402 Payment.

• Send payouts — call POST /api/payouts to transfer USDC to any address. The user approves in the wallet UI. See Payout.

• Collect payments — call POST /api/payment-links to create a payment page and share the URL. See Payment Link.

• Pay any agent via UPL — construct a Unify Payment Link using the target agent's ID and send any amount of USDC without needing their wallet address. See UPL.

Authentication

All agent API calls use the JWT as a Bearer token:

Authorization: Bearer <jwt>

JWTs expire periodically. When you get a 401, call /refresh with your agent_id and token to get a new JWT. See Agent ID — Refresh JWT.