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 (
scripts/fluxa-cli.bundle.js
).
Setup
The CLI bundle is located at
scripts/fluxa-cli.bundle.js
within this skill directory. It requires Node.js v18+.
bash
node scripts/fluxa-cli.bundle.js <command> [options]
All commands output JSON to stdout:
json
{ "success": true, "data": { ... } }
Or on error:
json
{ "success": false, "error": "Error message" }
Exit code
= success,
= failure.
Capabilities
| Capability | What it does | When to use |
|---|
| x402 Payment (v3) | Pay for APIs using the x402 protocol with intent mandates | Agent hits HTTP 402, needs to pay for API access |
| Payout | Send USDC to any wallet address | Agent needs to transfer funds to a recipient |
| Payment Link | Create shareable URLs to receive payments | Agent needs to charge users, create invoices, sell content |
Prerequisites — Register Agent ID
Before any operation, the agent must have an Agent ID. Register once:
bash
node scripts/fluxa-cli.bundle.js init \
--email "agent@example.com" \
--name "My AI Agent" \
--client "Agent v1.0"
Or pre-configure via environment variables:
bash
export AGENT_ID="ag_xxxxxxxxxxxx"
export AGENT_TOKEN="tok_xxxxxxxxxxxx"
export AGENT_JWT="eyJhbGciOiJ..."
Verify status:
bash
node scripts/fluxa-cli.bundle.js 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:
-
Always ask the user first using
tool with options:
- "Yes, open the link"
- "No, show me the URL"
-
If user chooses YES: Use the
command to open the URL in their default browser:
-
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 ( from )
- Payout approval ( from )
- Agent registration (if manual registration is needed)
Quick Decision Guide
| I want to... | Document |
|---|
| Pay for an API that returned HTTP 402 | X402-PAYMENT.md |
| Pay to a payment link (agent-to-agent) | PAYMENT-LINK.md — "Paying TO a Payment Link" section |
| Send USDC to a wallet address | PAYOUT.md |
| Create a payment link to receive payments | PAYMENT-LINK.md — "Create Payment Link" section |
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
for
must be the
complete 402 response JSON including the
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):
| Human-readable | Atomic units |
|---|
| 0.01 USDC | |
| 0.10 USDC | |
| 1.00 USDC | |
| 10.00 USDC | |
CLI Commands Quick Reference
| Command | Required Flags | Description |
|---|
| (none) | Check agent configuration |
| , | Register agent ID |
| , | Create an intent mandate |
| | Query mandate status (NOT ) |
| , | Execute x402 v3 payment |
| , , | Create a payout |
| | Query payout status |
| | Create a payment link |
| (none) | List payment links |
| | Get payment link details |
| | Update a payment link |
| | Delete a payment link |
| | Get payment records for a link |
Common Mistakes to Avoid:
| Wrong | Correct |
|---|
mandate-create --amount 100000
| mandate-create --desc "..." --amount 100000
|
mandate-status --mandate mand_xxx
| mandate-status --id mand_xxx
|
x402-v3 --payload '{"maxAmountRequired":"100000"}'
| x402-v3 --payload '<full 402 response with accepts array>'
|
Environment Variables
| Variable | Description |
|---|
| Pre-configured agent ID |
| Pre-configured agent token |
| Pre-configured agent JWT |
| Email for auto-registration |
| Agent name for auto-registration |
| Client info for auto-registration |
| Custom data directory (default: ) |
| Wallet API base URL (default: https://walletapi.fluxapay.xyz
|
| Agent ID API base URL (default: https://agentid.fluxapay.xyz
|