AI Agent Guide

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

The guides in this section show the raw HTTP flows, for backends and custom agent runtimes. If your agent can run shell commands, the fluxa-agent-wallet skill and the FluxA Wallet CLI do the same things with less code. Each guide includes a short With the CLI section.

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
Third-Party Login (VC)	Issue a Verifiable Credential to log in to a non-FluxA service with the Agent ID	Log in to Third-Party
Agent Cards	Issue prepaid virtual cards for the agent to pay at online checkouts	AgentCard
AgentMarket	Discover and pay for APIs, models and skills; call LLMs on prepaid Units or a Token Plan	AgentMarket

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.

With the CLI

The same quick start with the FluxA Wallet CLI:

npm install -g @fluxa-pay/fluxa-wallet@latest
fluxa-wallet init --name "My Agent" --client "my-app-v1"   # register
fluxa-wallet link-wallet                                    # user opens the URL to authorize
fluxa-wallet mandate-create --desc "API budget" --amount 1000000
fluxa-wallet x402 --mandate <mandateId> --payload '<402 response>'

The CLI stores credentials and refreshes the JWT for you.

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.