FluxA Wallet CLI

fluxa-wallet is the command-line client for the FluxA Agent Wallet. It gives an AI agent (or a script) a single binary to:

• register an Agent ID and link it to a user's FluxA Wallet,
• read the linked wallet's address, balances, mandates and recent transactions,
• create user-signed spending mandates and pay x402 APIs within them,
• send payouts, create payment links, and handle refunds,
• issue and manage prepaid agent cards (AgentCard),
• discover and pay for AgentMarket APIs, models and Token Plans (AgentMarket),
• pay merchant checkouts with the user's linked card (Beta).

The agent requests; the user approves. Anything that moves money either needs the user to approve a link in the wallet, or runs inside a mandate the user has already signed.

Install

Requires Node.js 18 or newer.

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

The package is @fluxa-pay/fluxa-wallet; the binary it installs is fluxa-wallet. These pages describe version 0.5.3.

Upgrade

Re-run the install command. Your Agent ID and credentials are kept, because they live in the data directory and not in the package (see Setup).

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

If a command fails in a way these docs don't explain, upgrade first. The wallet service changes faster than an old CLI does.

Version

fluxa-wallet --version    # or: fluxa-wallet -v, fluxa-wallet version
# 0.5.3

Usage

fluxa-wallet <command> [options]
fluxa-wallet --help               # all commands
fluxa-wallet <command> --help     # options for one command

Options are always --name value. A flag given without a value (for example --global or --yes) is treated as true. A value cannot start with --.

Output and exit codes

Most commands print a JSON envelope to stdout:

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

On failure every command prints:

{
  "success": false,
  "error": "Human-readable message",
  "code": "machine_readable_code"
}

code (and sometimes details) appear only when the service returns them.

Some read commands print their value directly, with no envelope, so they pipe cleanly:

Command	Prints on success
wallet-address	The bare address string
balance, mandates, recent-transactions	Bare JSON
card … (all card commands)	Bare JSON (object, array, or null)
linked-card list / mandates / subcard	Bare JSON
market …, plan-tool-use	Formatted text for people to read
version	The version string

Errors always use the envelope, whatever the command.

Exit code	Meaning
0	Success (also --help and --version)
1	Failure, or an unknown command (the usage text is printed too)

Progress and diagnostic lines (for example JWT expired or expiring soon, refreshing... or a topup waiting for approval) go to stderr, so stdout stays valid JSON.

# Scripting: test success, then read a field
RESULT=$(fluxa-wallet mandate-status --id mand_xxx)
echo "$RESULT" | jq -e '.success' >/dev/null && echo "$RESULT" | jq -r '.data.mandate.status'

Amounts and units

Units differ by command. Each reference page states the unit for every flag. In summary:

Where	Unit	Example
USDC (payouts, mandates, payment links, refunds, x402)	Atomic units, 6 decimals	1000000 = 1.00 USDC
XRP mandates	Atomic units, 6 decimals	1000000 = 1 XRP
Monetize Credits mandates (FLUXA_MONETIZE_CREDITS)	Atomic units, 2 decimals	500 = 5.00 credits
Linked-card mandates (CARD_USD)	US cents	3000 = $30.00
Agent cards (card create, recharge, withdraw)	USD decimal, at most 2 decimal places	25.00
AgentMarket Units	1 Unit = $0.00001; 100,000 Units = 1 credit = $1

Command map

Area	Commands	Page
Setup	status, init, check-wallet, link-wallet, refreshJWT	Setup
Account & identity	wallet-address, balance, mandates, recent-transactions, agent-vc, version	Account & identity
Mandates & x402	mandate-create, mandate-status, x402, x402-v3	Mandates & x402 payments
Payouts	payout, payout-status	Payouts
Receiving	paymentlink-*, received-records, received-record, paymentlink-refund-*	Payment links & refunds
Agent cards	card …	Agent cards
AgentMarket	market …, plan-tool-use	AgentMarket
Linked card (Beta)	linked-card …, headless-checkout, mandate-create --currency CARD_USD	Linked card

Problems? See Troubleshooting.