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+.
CODEBLOCK0
All commands output JSON to stdout:
CODEBLOCK1
Or on error:
CODEBLOCK2
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:
CODEBLOCK3
Or pre-configure via environment variables:
CODEBLOCK4
Verify status:
CODEBLOCK5
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:
CODEBLOCK6
- 3. If user chooses NO: Display the URL and ask how they'd like to proceed.
Example interaction flow:
CODEBLOCK7
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 |
| 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:
CODEBLOCK8
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):
| Human-readable | Atomic units |
|---|
| 0.01 USDC | INLINECODE13 |
| 0.10 USDC |
100000 |
| 1.00 USDC |
1000000 |
| 10.00 USDC |
10000000 |
CLI Commands Quick Reference
| Command | Required Flags | Description |
|---|
| INLINECODE17 | (none) | Check agent configuration |
| INLINECODE18 |
--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 |
|---|
| INLINECODE47 | INLINECODE48 |
| INLINECODE49 |
mandate-status --id mand_xxx |
|
x402-v3 --payload '{"maxAmountRequired":"100000"}' |
x402-v3 --payload '<full 402 response with accepts array>' |
Environment Variables
| Variable | Description |
|---|
| INLINECODE53 | Pre-configured agent ID |
| INLINECODE54 |
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) |
FluxA Agent Wallet
FluxA Agent Wallet 让 AI 代理能够执行链上金融操作——支付、付款和支付链接——而无需管理私钥。所有操作均使用 CLI（scripts/fluxa-cli.bundle.js）。
设置
CLI 包位于此技能目录中的 scripts/fluxa-cli.bundle.js。需要 Node.js v18+。
bash
node scripts/fluxa-cli.bundle.js <命令> [选项]
所有命令均以 JSON 格式输出到标准输出：
json
{ success: true, data: { ... } }
或错误时：
json
{ success: false, error: 错误信息 }
退出码 0 = 成功，1 = 失败。
功能
| 功能 | 作用 | 使用场景 |
|---|
| x402 支付 (v3) | 使用 x402 协议通过意图授权进行 API 支付 | 代理遇到 HTTP 402，需要支付 API 访问费用 |
| 付款 |
向任意钱包地址发送 USDC | 代理需要向收款人转账 |
|
支付链接 | 创建可分享的 URL 以接收付款 | 代理需要向用户收费、创建发票、出售内容 |
前提条件——注册代理 ID
在任何操作之前，代理必须拥有一个代理 ID。注册一次：
bash
node scripts/fluxa-cli.bundle.js init \
--email agent@example.com \
--name My AI Agent \
--client Agent v1.0
或通过环境变量预配置：
bash
export AGENTID=agxxxxxxxxxxxx
export AGENTTOKEN=tokxxxxxxxxxxxx
export AGENT_JWT=eyJhbGciOiJ...
验证状态：
bash
node scripts/fluxa-cli.bundle.js status
CLI 会自动刷新过期的 JWT。
打开授权 URL（用户体验模式）
许多操作需要通过 URL 进行用户授权（授权签署、付款批准、代理注册）。当您需要用户打开 URL 时：
- 1. 始终先询问用户，使用 AskUserQuestion 工具并提供选项：
- 是，打开链接
- 否，显示 URL
- 2. 如果用户选择是：使用 open 命令在默认浏览器中打开 URL：
bash
open
- 3. 如果用户选择否：显示 URL 并询问用户希望如何继续。
示例交互流程：
代理：我需要打开授权 URL 以签署授权。
[是，打开链接] [否，显示 URL]
用户：[是，打开链接]
代理：运行 open https://agentwallet.fluxapay.xyz/onboard/intent?oid=...
代理：我已打开浏览器中的授权页面。请签署授权，完成后请告知我。
此模式适用于：
- - 授权授权（来自 mandate-create 的 authorizationUrl）
- 付款批准（来自 payout 的 approvalUrl）
- 代理注册（如需手动注册）
快速决策指南
PAYMENT-LINK.md — 向支付链接付款 部分 |
| 向钱包地址发送 USDC | PAYOUT.md |
| 创建支付链接以接收付款 | PAYMENT-LINK.md — 创建支付链接 部分 |
常见流程：向支付链接付款
这是一个使用 CLI 的 6 步流程：
- 1. PAYLOAD=$(curl -s <支付链接 URL>) → 获取完整的 402 负载 JSON
- mandate-create --desc ... --amount <金额> → 创建授权（两个标志都必须）
- 用户在 authorizationUrl 签署 → 授权变为 已签署
- mandate-status --id → 验证已签署（使用 --id，而非 --mandate）
- x402-v3 --mandate --payload $PAYLOAD → 获取 xPaymentB64（传递完整的 402 JSON）
- curl -H X-Payment: → 提交支付
关键点： x402-v3 的 --payload 必须是 完整的 402 响应 JSON，包括 accepts 数组，而不仅仅是提取的字段。
请参阅 PAYMENT-LINK.md 获取包含示例的完整指南。
金额格式
所有金额均以 最小单位（原子单位）表示。对于 USDC（6 位小数）：
| 人类可读 | 原子单位 |
|---|
| 0.01 USDC | 10000 |
| 0.10 USDC |
100000 |
| 1.00 USDC | 1000000 |
| 10.00 USDC | 10000000 |
CLI 命令快速参考
| 命令 | 必需标志 | 描述 |
|---|
| status | （无） | 检查代理配置 |
| init |
--email, --name | 注册代理 ID |
| mandate-create | --desc, --amount | 创建意图授权 |
| mandate-status | --id | 查询授权状态（不是 --mandate） |
| x402-v3 | --mandate, --payload | 执行 x402 v3 支付 |
| payout | --to, --amount, --id | 创建付款 |
| payout-status | --id | 查询付款状态 |
| paymentlink-create | --amount | 创建支付链接 |
| paymentlink-list | （无） | 列出支付链接 |
| paymentlink-get | --id | 获取支付链接详情 |
| paymentlink-update | --id | 更新支付链接 |
| paymentlink-delete | --id | 删除支付链接 |
| paymentlink-payments | --id | 获取链接的支付记录 |
常见错误避免：
| 错误 | 正确 |
|---|
| mandate-create --amount 100000 | mandate-create --desc ... --amount 100000 |
| mandate-status --mandate mandxxx |
mandate-status --id mandxxx |
| x402-v3 --payload {maxAmountRequired:100000} | x402-v3 --payload <包含 accepts 数组的完整 402 响应> |
环境变量
| 变量 | 描述 |
|---|
| AGENTID | 预配置的代理 ID |
| AGENTTOKEN |
预配置的代理令牌 |
| AGENT_JWT | 预配置的代理 JWT |
| AGENT_EMAIL | 自动注册的邮箱 |
| AGENT_NAME | 自动注册的代理名称 |
| CLIENT_INFO | 自动注册的客户端信息 |
| FLUXADATADIR | 自定义数据目录（默认：~/.fluxa-ai-wallet-mcp） |
| WALLET_API | 钱包 API 基础 URL（默认：https://walletapi.fluxapay.xyz） |
| AGENTIDAPI | 代理 ID API 基础 URL（默认：https://agentid.fluxapay.xyz） |
