fluxa-agent-wallet
fluxa-agent-wallet is FluxA's main Agent Skill. It gives an AI agent a co-wallet: the agent asks to spend, receive or move funds, and the user approves the scope (a one-off approval, or a budget called a mandate). The agent does all of this through the FluxA Wallet CLI (@fluxa-pay/fluxa-wallet). Every command prints JSON, and no private keys or payment code live in the agent.
| Current version | Skill 0.5.3, requires CLI @fluxa-pay/fluxa-wallet 0.5.3 or newer |
| Runtime | Node.js 18+ (for the CLI) |
| Source | github.com/FluxA-Agent-Payment/FluxA-AI-Wallet-MCP/tree/main/skills/fluxa-agent-wallet |
| Live copy | https://fluxapay.xyz/skill.md |
Install
Option 1: let the agent install it. Paste this into your agent:
Read and install https://fluxapay.xyz/skill.mdOption 2: install with the skills installer.
npx skills add -s fluxa-agent-wallet -y -g FluxA-Agent-Payment/FluxA-AI-Wallet-MCPEither way, the agent then runs the skill's Setup:
npm install -g @fluxa-pay/fluxa-wallet@latest
fluxa-wallet --version # 0.5.3 or newer
fluxa-wallet status # already configured? skip init
fluxa-wallet init --name "My AI Agent" --client "Claude Code on macOS"
fluxa-wallet check-wallet # linked: false → run link-wallet
fluxa-wallet link-wallet # returns a URL for the user to openThe user opens the link-wallet URL and approves the agent in the FluxA Wallet. Credentials are saved locally in ~/.fluxa-ai-wallet-mcp/config.json (set FLUXA_DATA_DIR to use another directory). See CLI › Setup for every option.
Keeping up to date
If payments start failing with errors the agent can't resolve, update both pieces: reinstall the skill from https://fluxapay.xyz/skill.md and run npm install -g @fluxa-pay/fluxa-wallet@latest.
How approvals work
- Spending needs approval. The agent shows the cost and gets your explicit choice before it spends. For repeated spending, such as paid APIs, it asks for a mandate: a budget with an amount, a time window and a purpose, which you sign once.
- The agent plans budgets per task. It reuses an existing signed mandate when one fits (
fluxa-wallet mandates) and sizes a new one for the whole task, not one per call. For pay-per-call APIs it asks for a budget that covers about 100 calls by default, so you aren't asked again on every call. - Approval links are clickable. When your approval is needed (linking the wallet, signing a mandate, approving a payout), the agent gives you the full URL to open.
- Costs are reported honestly. After AgentMarket model calls, the agent reports the cost. A negative Units balance means usage that hasn't been paid for yet, and the agent tells you so.
Capabilities
The skill covers more than the CLI's payment basics. Each row points to where it's documented. The CLI pages hold the full command reference.
| Capability | What the agent can do | Main commands | Docs |
|---|---|---|---|
| x402 payments | Pay HTTP 402 APIs from a signed mandate, then retry the request with the payment header | mandate-create, mandate-status, mandates, x402 | CLI › Payments, X402 Payment guide |
| Payout | Send USDC on Base to any wallet address, with approval per payout or within a signed mandate | payout, payout-status | CLI › Payouts, Payout guide |
| Transfer to agent | Send USDC to another agent using only its Agent ID, through its Unify Payment Link | mandate-create, x402 | UPL guide |
| Payment links | Create, list, update and delete links that collect USDC, optionally delivering content after payment | paymentlink-* | CLI › Receiving, Payment Link guide |
| Received payments & refunds | List incoming payments, then issue full or partial refunds for payment-link payments | received-records, received-record, paymentlink-refund-* | CLI › Receiving |
| Agent cards | Issue prepaid virtual cards for the agent, check balances and transactions, recharge or withdraw, and read 3DS codes | card ... | AgentCard |
| Linked card (beta) | Pay a supported merchant checkout with the user's own linked card, within a merchant-scoped card mandate. The agent never sees the card number | linked-card ..., headless-checkout | CLI › Linked card |
| Agent VC & Agent ID | Issue a short-lived Verifiable Credential to sign in to a third-party service without sharing the agent's login token | agent-vc | Log in to Third-Party, CLI › Account |
| AgentMarket: discover & plan | Search paid APIs, models and skills, and get a recommended tool plan for a task | market search, plan-tool-use, market info | AgentMarket |
| Models on Units | Call OpenAI-compatible LLMs from one prepaid Units balance, check the balance and history, and top it up with USDC or Monetize Credits | market model remainingUsage, market model usageHistory, market model topup | Models & Units |
| Token Plan | Buy a monthly model allowance on a provider's own endpoint | market tokenplan ... | Token Plans |
| AgentMarket API keys | Create, cap, update and revoke fxa_live_ keys for apps and services | market keys ... | API keys |
| Wallet overview | Show the wallet address, balances, mandates and recent spending | wallet-address, balance, mandates, recent-transactions | CLI › Account |
Scheduled tasks
If your agent runtime supports scheduled tasks, the skill can set up two recurring jobs:
| Task | What it does | Suggested schedule |
|---|---|---|
| Daily wallet check | Summarizes yesterday's incoming payments and relevant FluxA announcements | Daily at 10:00 and 18:00 in your timezone |
| Token usage management & auto top-up | Watches AgentMarket model usage and the Units balance, analyzes spend per API key, suggests cheaper models, and tops up automatically within the rules you approved (trigger, bundle, currency and spending scope) | Twice a day |
Automatic top-ups only use a mandate you have already signed for that purpose. Widening the scope needs your approval again.
Funding the wallet
You add and manage funds in the FluxA Wallet:
- USDC: pay by credit card, send USDC on Base to the wallet address (
fluxa-wallet wallet-address), or bridge from another chain. - Monetize Credits: bought by credit card and spendable only on AgentMarket resources. Credits can't be transferred or used as general USDC.
Amounts in CLI commands are in atomic units: 1000000 = 1 USDC.
Skill contents
fluxa-agent-wallet/
├── SKILL.md ← Setup, rules, capability map, CLI quick reference
├── MANDATE-PLANNING.md ← How to size and reuse budgets
├── X402-PAYMENT.md ← Paying x402 APIs
├── x402-SERVICES.md ← Finding paid APIs and models on AgentMarket
├── TRY-ONESHOT-API.md ← Guided first paid-API demo
├── PAYOUT.md ← Sending USDC to an address
├── TRANSFER-TO-AGENT.md ← Sending USDC to an Agent ID (UPL)
├── PAYMENT-LINK.md ← Payment links, received payments, refunds
├── LINKED-CARD.md ← Paying with the user's linked card (beta)
├── VC-ISSUE.md ← Agent Verifiable Credentials
├── TOKENPLAN.md ← Monthly Token Plans
├── TOKEN-MANAGEMENT.md ← Scheduled usage management & auto top-up
├── SCHEDULED-CHECKIN.md ← Scheduled daily wallet check
├── CLAWPI.md ← ClawPI social gifting walkthrough
└── INTEGRATION-GUIDE-*.md ← Guides for developers integrating with agentsThere's no bundled script. The skill drives the fluxa-wallet CLI from npm.
Related
- FluxA Wallet CLI: full command reference
- agentic-checkout skill (beta)
- MCP Server: for clients that support MCP tools only