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 (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+.

node scripts/fluxa-cli.bundle.js  [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

| 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:

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:

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

Verify status:

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:

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

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

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

``bash open "" ``

1. 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

| I want to... | Document | |--------------|----------| | Pay for an API that returned HTTP 402 | [X402-PAYMENT.md](X402-PAYMENT.md) | | Pay to a payment link (agent-to-agent) | [PAYMENT-LINK.md](PAYMENT-LINK.md) — "Paying TO a Payment Link" section | | Send USDC to a wallet address | [PAYOUT.md](PAYOUT.md) | | Create a payment link to receive payments | [PAYMENT-LINK.md](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 )                    → Get full 402 payload JSON
2. mandate-create --desc "..." --amount             → Create mandate (BOTH flags required)
3. User signs at authorizationUrl                           → Mandate becomes "signed"
4. mandate-status --id                          → Verify signed (use --id, NOT --mandate)
5. x402-v3 --mandate  --payload "$PAYLOAD"              → Get xPaymentB64 (pass FULL 402 JSON)
6. curl -H "X-Payment: "                        → 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](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 | 10000 | | 0.10 USDC | 100000 | | 1.00 USDC | 1000000 | | 10.00 USDC | 10000000 |

CLI Commands Quick Reference

| Command | Required Flags | Description | |---------|----------------|-------------| | status | (none) | Check agent configuration | | init | --email, --name | Register agent ID | | mandate-create | --desc, --amount | Create an intent mandate | | mandate-status | --id | Query mandate status (NOT --mandate) | | x402-v3 | --mandate, --payload | Execute x402 v3 payment | | payout | --to, --amount, --id | Create a payout | | payout-status | --id | Query payout status | | paymentlink-create | --amount | Create a payment link | | paymentlink-list | (none) | List payment links | | paymentlink-get | --id | Get payment link details | | paymentlink-update | --id | Update a payment link | | paymentlink-delete | --id | Delete a payment link | | paymentlink-payments | --id | 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 '' |

Environment Variables

| Variable | Description | |----------|-------------| | AGENT_ID | Pre-configured agent ID | | AGENT_TOKEN | Pre-configured agent token | | AGENT_JWT | Pre-configured agent JWT | | AGENT_EMAIL | Email for auto-registration | | AGENT_NAME | Agent name for auto-registration | | CLIENT_INFO | Client info for auto-registration | | FLUXA_DATA_DIR | Custom data directory (default: ~/.fluxa-ai-wallet-mcp) | | WALLET_API | Wallet API base URL (default: https://walletapi.fluxapay.xyz) | | AGENT_ID_API | Agent ID API base URL (default: https://agentid.fluxapay.xyz) |

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: deancourse
• Source: deancourse/user-dot-agents
• License: MIT

Install and usage instructions live in the source repository linked above.