Back to Details

fluxa-agent-wallet

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

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
).
FluxA Agent Wallet 让AI Agent无需管理私钥即可执行链上金融操作——支付、付款和支付链接。所有操作均使用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 
0
= success, 
1
= failure.
CLI包位于本skill目录下的
scripts/fluxa-cli.bundle.js
，需要Node.js v18或更高版本。
bash
node scripts/fluxa-cli.bundle.js <command> [options]
所有命令会将JSON输出到标准输出：
json
{ "success": true, "data": { ... } }
错误时输出：
json
{ "success": false, "error": "Error message" }
退出码
0
表示成功，
1
表示失败。

Capabilities

功能特性

CapabilityWhat it doesWhen to use
x402 Payment (v3)Pay for APIs using the x402 protocol with intent mandatesAgent hits HTTP 402, needs to pay for API access
PayoutSend USDC to any wallet addressAgent needs to transfer funds to a recipient
Payment LinkCreate shareable URLs to receive paymentsAgent needs to charge users, create invoices, sell content
功能说明使用场景
x402 Payment (v3)使用带有意图委托的x402协议为API付费Agent收到HTTP 402响应，需要付费以获取API访问权限
付款（Payout）向任意钱包地址发送USDCAgent需要向接收方转账资金
支付链接（Payment Link）创建可分享的URL以接收付款Agent需要向用户收费、创建发票、售卖内容

Prerequisites — Register Agent ID

前置条件 — 注册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.
在执行任何操作前，Agent必须拥有一个Agent ID。只需注册一次：
bash
node scripts/fluxa-cli.bundle.js init \
  --email "agent@example.com" \
  --name "My AI Agent" \
  --client "Agent v1.0"
也可通过环境变量预先配置：
bash
export AGENT_ID="ag_xxxxxxxxxxxx"
export AGENT_TOKEN="tok_xxxxxxxxxxxx"
export AGENT_JWT="eyJhbGciOiJ..."
验证状态：
bash
node scripts/fluxa-cli.bundle.js status
CLI会自动刷新过期的JWT。

Opening Authorization URLs (UX Pattern)

打开授权URL（UX模式）

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:
    bash
    open "<URL>"
  3. 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)
许多操作需要用户通过URL授权（委托签名、付款审批、Agent注册）。当需要用户打开URL时：
  1. 务必先询问用户，使用
    AskUserQuestion
    工具提供以下选项：
    • "是，打开链接"
    • "否，显示URL"
  2. 如果用户选择“是”：使用
    open
    命令在默认浏览器中打开URL：
    bash
    open "<URL>"
  3. 如果用户选择“否”：显示URL并询问用户希望如何操作。
交互流程示例：
Agent: 我需要打开授权URL来签署委托协议。
       [是，打开链接] [否，显示URL]

用户: [是，打开链接]

Agent: *执行* open "https://agentwallet.fluxapay.xyz/onboard/intent?oid=..."
Agent: 我已在你的浏览器中打开了授权页面。请签署委托协议，完成后告知我。
此模式适用于：
  • 委托授权（
    mandate-create
    返回的
    authorizationUrl
    ）
  • 付款审批（
    payout
    返回的
    approvalUrl
    ）
  • Agent注册（如需手动注册）

Quick Decision Guide

快速决策指南

I want to...Document
Pay for an API that returned HTTP 402X402-PAYMENT.md
Pay to a payment link (agent-to-agent)PAYMENT-LINK.md — "Paying TO a Payment Link" section
Send USDC to a wallet addressPAYOUT.md
Create a payment link to receive paymentsPAYMENT-LINK.md — "Create Payment Link" section
我想要...参考文档
为返回HTTP 402的API付费X402-PAYMENT.md
向支付链接付款（Agent间转账）PAYMENT-LINK.md — “向支付链接付款”章节
向钱包地址发送USDCPAYOUT.md
创建支付链接以接收付款PAYMENT-LINK.md — “创建支付链接”章节

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 
--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.
这是一个使用CLI的6步流程：
1. PAYLOAD=$(curl -s <payment_link_url>)                    → 获取完整的402负载JSON
2. mandate-create --desc "..." --amount <amount>            → 创建委托协议（两个参数均为必填）
3. 用户在authorizationUrl处签署协议                           → 委托协议变为“已签署”状态
4. mandate-status --id <mandate_id>                         → 验证协议已签署（使用--id，而非--mandate）
5. x402-v3 --mandate <id> --payload "$PAYLOAD"              → 获取xPaymentB64（传入完整的402 JSON）
6. curl -H "X-Payment: <token>" <url>                       → 提交付款
关键注意事项：
x402-v3
的
--payload
必须是完整的402响应JSON，包含
accepts
数组，而非仅提取部分字段。
详细内容请参考PAYMENT-LINK.md中的完整示例步骤。

Amount Format

金额格式

All amounts are in smallest units (atomic units). For USDC (6 decimals):
Human-readableAtomic units
0.01 USDC
10000
0.10 USDC
100000
1.00 USDC
1000000
10.00 USDC
10000000
所有金额均以最小单位（原子单位）表示。对于USDC（6位小数）：
易读格式原子单位
0.01 USDC
10000
0.10 USDC
100000
1.00 USDC
1000000
10.00 USDC
10000000

CLI Commands Quick Reference

CLI命令速查

CommandRequired FlagsDescription
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:
WrongCorrect
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>'
命令必填参数说明
status
无检查Agent配置
init
--email
, 
--name
注册Agent ID
mandate-create
--desc
, 
--amount
创建意图委托协议
mandate-status
--id
查询委托协议状态（使用--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 mand_xxx
mandate-status --id mand_xxx
x402-v3 --payload '{"maxAmountRequired":"100000"}'
x402-v3 --payload '<包含accepts数组的完整402响应>'

Environment Variables

环境变量

VariableDescription
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
)
变量名说明
AGENT_ID
预配置的Agent ID
AGENT_TOKEN
预配置的Agent令牌
AGENT_JWT
预配置的Agent JWT
AGENT_EMAIL
自动注册用的邮箱
AGENT_NAME
自动注册用的Agent名称
CLIENT_INFO
自动注册用的客户端信息
FLUXA_DATA_DIR
自定义数据目录（默认：
~/.fluxa-ai-wallet-mcp
）
WALLET_API
钱包API基础URL（默认：
https://walletapi.fluxapay.xyz
）
AGENT_ID_API
Agent ID API基础URL（默认：
https://agentid.fluxapay.xyz
）