Fluxa Agent Wallet

FluxA Agent Wallet

FluxA Agent Wallet lets AI agents perform onchain financial operations — payments, payouts, and payment links — without managing private keys. All operations use the CLI (fluxa-wallet).

Setup

Install the CLI globally:

npm install -g @fluxa-pay/fluxa-wallet

Then run commands directly:

fluxa-wallet <command> [options]

All commands output JSON to stdout:

{ "success": true, "data": { ... } }

Or on error:

{ "success": false, "error": "Error message" }

Exit code 0 = success, 1 = failure.

Capabilities

Prerequisites — Register Agent ID

Before any operation, the agent must have an Agent ID. Register once:

fluxa-wallet init \
  --name "My AI Agent" \
  --client "Agent v1.0"

Or pre-configure via environment variables:

export AGENT_ID="ag_xxxxxxxxxxxx"
export AGENT_TOKEN="tok_xxxxxxxxxxxx"
export AGENT_JWT="eyJhbGciOiJ..."

Verify status:

fluxa-wallet status

The CLI automatically refreshes expired JWTs.

Opening Authorization URLs (UX Pattern)

Many operations require user authorization via a URL (mandate signing, payout approval, agent registration). When you need the user to open a URL:

1. Always ask the user first using AskUserQuestion tool with options:

   • "Yes, open the link"
   • "No, show me the URL"

2. If user chooses YES: Use the open command to open the URL in their default browser:

   open "<URL>"
   

3. If user chooses NO: Display the URL and ask how they'd like to proceed.

Example interaction flow:

Agent: I need to open the authorization URL to sign the mandate.
       [Yes, open the link] [No, show me the URL]

User: [Yes, open the link]

Agent: *runs* open "https://agentwallet.fluxapay.xyz/onboard/intent?oid=..."
Agent: I've opened the authorization page in your browser. Please sign the mandate, then let me know when you're done.

This pattern applies to:

• Mandate authorization (authorizationUrl from mandate-create)
• Payout approval (approvalUrl from payout)
• Agent registration (if manual registration is needed)

Quick Decision Guide

Common Flow: Paying to a Payment Link

This is a 6-step process using CLI:

1. PAYLOAD=$(curl -s <payment_link_url>)                    → Get full 402 payload JSON
2. mandate-create --desc "..." --amount <amount>            → Create mandate (BOTH flags required)
3. User signs at authorizationUrl                           → Mandate becomes "signed"
4. mandate-status --id <mandate_id>                         → Verify signed (use --id, NOT --mandate)
5. x402-v3 --mandate <id> --payload "$PAYLOAD"              → Get xPaymentB64 (pass FULL 402 JSON)
6. curl -H "X-Payment: <token>" <url>                       → Submit payment

Critical: The --payload for x402-v3 must be the complete 402 response JSON including the accepts array, not just extracted fields.

See PAYMENT-LINK.md for the complete walkthrough with examples.

Amount Format

All amounts are in smallest units (atomic units). For USDC (6 decimals):

CLI Commands Quick Reference

Common Mistakes to Avoid:

Environment Variables