FluxA AI钱包MCP

FluxA AI钱包的MCP服务器，支持x402（确切地说是EIP-3009）支付。

包裹

此存储库包含两个包：

软件包	说明	安装
`@fluxa-pay/fluxa-wallet-mcp`	用于AI代理框架的MCP服务器（Claude Desktop等）	`npm install @fluxa-pay/fluxa-wallet-mcp`
`@fluxa-pay/fluxa-wallet`	用于脚本和自动化的独立CLI	`npm install -g @fluxa-pay/fluxa-wallet`

概述

此MCP服务器使AI代理能够使用FluxA Wallet API进行x402付款。它为代理注册、验证和执行区块链支付提供了一个简单的接口，而无需在本地管理私钥。

特性

代理ID管理：注册和管理FluxA代理ID
x402支付支持：通过FluxA Wallet API生成EIP-3009支付授权
自动JWT刷新：付款前自动刷新过期的JWT代币
无本地密钥管理：所有签名均由FluxA钱包处理（无本地私钥）
政策管理：FluxA Wallet远程管理策略
环境变量支持：通过env变量或配置文件进行配置

快速开始

命令行界面

npm install -g @fluxa-pay/fluxa-wallet
fluxa-wallet status

MCP服务器

npm install
npm run build
npm start

发展

npm run dev

构建

# Build MCP server only
npm run build

# Build CLI bundle only
npm run build:wallet

# Build both
npm run build:all

配置

服务器将配置存储在 ~/.fluxa-ai-wallet-mcp/config.json 默认情况下。

您可以覆盖数据目录：

export FLUXA_DATA_DIR=/path/to/custom/dir

代理ID配置

有 两种方法 通过环境变量配置代理ID：

方法1：使用现有凭据（最高优先级）

如果您已经拥有代理ID凭据，请设置以下环境变量：

export AGENT_ID=your-agent-id
export AGENT_TOKEN=your-token
export AGENT_JWT=your-jwt

此方法绕过注册，直接使用提供的凭据。

方法2：提供注册信息

如果您还没有凭据，请配置注册信息：

export AGENT_NAME="Claude Desktop - John's MacBook"
export CLIENT_INFO="Claude Desktop v1.0 on macOS 14.1"

当这些设置完成后，调用 init_agent_id 参数为空 {} 将使用此信息自动注册。

优先级顺序：

方法1环境变量（AGENT_ID+AGENT_TOKEN+AGENT_JWT）
配置文件(~/.fluxa-ai-wallet-mcp/config.json)
方法2环境变量（需要调用 init_agent_id)
手动注册（需要用户输入）

MCP工具

1. `init_agent_id`

注册新的FluxA代理ID。付款前必须调用该ID。

配置方法：

此工具支持两种方式提供注册信息：

使用环境变量（上述方法2）：如果 AGENT_NAME 和 CLIENT_INFO 设置，只需使用空参数调用：

{}

使用参数：如果未设置环境变量，请直接提供信息：

   {
     "agent_name": "Claude Desktop - John's MacBook",
     "client_info": "Claude Desktop v1.0 on macOS 14.1"
   }

输出：

{
  "status": "ok",
  "agent_id": "uuid-string",
  "message": "Agent ID registered successfully"
}

代理人使用：

如果配置了环境变量（方法2），只需调用 init_agent_id 随着 {}
否则：

1. 选择一个有意义的代理名称（例如，“Claude Desktop-用户的计算机”） 1. 提供客户端信息（例如，“macOS上的Claude Desktop v1.0”） 1. 使用收集到的参数调用此工具

2. `request_x402_payment`

通过调用FluxA Wallet API生成x402支付授权。

输入：

{
  "payment_required": {
    "x402Version": 1,
    "accepts": [{
      "scheme": "exact",
      "network": "base",
      "maxAmountRequired": "10000",
      "resource": "https://example.com/api/data",
      "description": "API access",
      "mimeType": "application/json",
      "payTo": "0x...",
      "maxTimeoutSeconds": 300,
      "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
      "extra": {
        "name": "USD Coin",
        "version": "2"
      }
    }]
  },
  "intent": {
    "why": "Access protected API endpoint",
    "http_method": "GET",
    "http_url": "https://example.com/api/data",
    "caller": "user-agent-name"
  },
  "options": {
    "validity_window_seconds": 60,
    "approval_id": "apprv_123"
  }
}

approval_id 是可选的。当钱包指示您完成外部审批流时提供它，以便重试可以链接到该审批。

输出：

{
  "status": "ok",
  "x_payment": "base64-encoded-payment-header",
  "x_payment_object": {
    "x402Version": 1,
    "scheme": "exact",
    "network": "base",
    "payload": { ... }
  }
}

错误（代理未注册）：

{
  "status": "error",
  "code": "agent_not_registered",
  "message": "FluxA Agent ID not configured. Please register first.",
  "pmc": {
    "primer": "Please read and follow pmc.instructions...",
    "instructions": "Agent ID is not configured. Please call init_agent_id..."
  }
}

错误（需要批准）：

{
  "status": "approval_required",
  "code": "approval_required",
  "message": "Approval required",
  "approvalId": "apprv_123",
  "approvalUrl": "https://wallet.fluxapay.xyz/approvals/apprv_123",
  "pmc": {
    "primer": "Please read and follow pmc.instructions...",
    "instructions": "Visit the approval URL, authorize the request, then call request_x402_payment again with options.approval_id=apprv_123."
  }
}

3. `request_payout`

通过FluxA Wallet API创建支付。

笔记：

金额必须以最小单位提供（例如，USDC有6位小数，因此 10000 =0.01美元直流电）
网络、货币和资产在MCP内硬编码到Base主网USDC（无需传递）
payout_id 是必需的，必须由调用者提供（幂等性密钥）

输入：

{
  "to_address": "0x4eb5b229d43c30fc629d92bf7ed415d6d7f0cabe",
  "amount": "10000",
  "payout_id": "payout-test-017"
}

输出（待授权）：

{
  "payoutId": "payout-test-017",
  "status": "pending_authorization",
  "txHash": null,
  "approvalUrl": "http://localhost:3000/authorize-payout/payout-test-017",
  "expiresAt": 1763914398
}

如果payoutId已存在，则状态可能为 succeeded 并包括 txHash.

4. `get_payout_status`

从钱包应用程序公共端点查询支付状态。在浏览器中授权支付后，这很有用。

输入：

{
  "payout_id": "payout-test-017"
}

输出：

{
  "payoutId": "payout-test-017",
  "status": "succeeded",
  "txHash": "0x..."
}

5. `get_agent_status`

查询当前代理ID配置状态。

输入： 无

输出：

{
  "configured": true,
  "agent_id": "uuid-string",
  "agent_name": "Claude Desktop - John's MacBook",
  "registered_at": "2024-01-01T00:00:00.000Z"
}

6. `create_intent_mandate`

为x402 v3付款创建意向授权。这是x402 v3流程的第一步。

输入：

{
  "intent": {
    "naturalLanguage": "I plan to spend up to 0.10 USDC to get Polymarket trading recommendations valid for 30 days.",
    "category": "trading_data",
    "currency": "USDC",
    "limitAmount": "100000",
    "validForSeconds": 2592000,
    "hostAllowlist": []
  }
}

输出：

{
  "status": "ok",
  "mandateId": "mand_xxxxxxxxxxxxx",
  "authorizationUrl": "https://wallet.fluxapay.xyz/onboard/intent?oid=...",
  "expiresAt": "2024-01-01T00:10:00.000Z",
  "agentStatus": "ready"
}

代理人使用：

使用intent参数调用此工具
请用户打开 authorizationUrl 授权并签署授权书
使用 mandateId 随着 request_x402_v3_payment 付款

7. `get_mandate_status`

查询意向授权的状态。

输入：

{
  "mandate_id": "mand_xxxxxxxxxxxxx"
}

输出：

{
  "status": "ok",
  "mandate": {
    "mandateId": "mand_xxxxxxxxxxxxx",
    "status": "signed",
    "naturalLanguage": "I plan to spend up to 0.10 USDC...",
    "currency": "USDC",
    "limitAmount": "100000",
    "spentAmount": "10000",
    "remainingAmount": "90000",
    "validFrom": "2024-01-01T00:00:00.000Z",
    "validUntil": "2024-01-31T00:00:00.000Z"
  }
}

8. `request_x402_v3_payment`

使用意向授权签署x402 v3付款。需要签名的mandateId。

输入：

{
  "mandate_id": "mand_xxxxxxxxxxxxx",
  "payment_required": {
    "x402Version": 1,
    "accepts": [{
      "scheme": "exact",
      "network": "base",
      "maxAmountRequired": "10000",
      "resource": "https://example.com/api/data",
      "description": "API access",
      "mimeType": "application/json",
      "payTo": "0x...",
      "maxTimeoutSeconds": 300,
      "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
      "extra": {
        "name": "USD Coin",
        "version": "2"
      }
    }]
  },
  "intent": {
    "why": "Access protected API endpoint",
    "http_method": "GET",
    "http_url": "https://example.com/api/data",
    "caller": "user-agent-name"
  }
}

输出：

{
  "status": "ok",
  "xPaymentB64": "eyJ4NDAyVmVyc2lvbi...",
  "xPayment": {
    "x402Version": 1,
    "scheme": "exact",
    "network": "base",
    "payload": { ... }
  },
  "paymentRecordId": 123,
  "expiresAt": 1700000060
}

错误（委托书未签署）：

{
  "status": "denied",
  "code": "mandate_not_signed",
  "message": "Mandate does not allow this payment",
  "payment_model_context": {
    "primer": "Please read and follow...",
    "instructions": "The mandate is not signed yet. Ask user to sign at signUrl."
  }
}

工作流程

首次设置

客服电话 request_x402_payment 未注册

- 服务器返回错误代码 agent_not_registered - PMC说明指导代理商注册

代理收集用户信息

- 根据环境生成有意义的代理名称 - 准备客户信息字符串

客服电话 init_agent_id

- 服务器使用FluxA代理ID API注册 - 返回agent_id、token和JWT - 配置会自动保存

代理重试 request_x402_payment

- 服务器使用JWT调用FluxA Wallet API - 返回已签名的付款授权 - 代理添加X-Payment标头并重试HTTP请求

后续付款

注册后，代理人可以直接致电 request_x402_payment 无需重新注册。JWT用于通过FluxA Wallet API进行身份验证。

API终点

FluxA代理ID API

基本URL: https://agentid.fluxapay.xyz

POST/注册

curl -X POST https://agentid.fluxapay.xyz/register \
  -H "Content-Type: application/json" \
  -d '{
    "agent_name": "My Agent",
    "client_info": "My Client v1.0"
  }'

答复：

{
  "agent_id": "uuid-string",
  "token": "token-string",
  "jwt": "jwt-string"
}

FluxA钱包API

基本URL: https://walletapi.fluxapay.xyz

POST/api/支付/x402V1支付

curl -X POST https://walletapi.fluxapay.xyz/api/payment/x402V1Payment \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $JWT_TOKEN" \
  -d '{
    "scheme": "exact",
    "network": "base",
    "amount": "10000",
    "currency": "USDC",
    "assetAddress": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
    "payTo": "0x...",
    "host": "example.com",
    "resource": "https://example.com/api/data",
    "description": "API access",
    "tokenName": "USD Coin",
    "tokenVersion": "2",
    "validityWindowSeconds": 60
  }'

x402 v3付款（意向委托书）

x402 v3需要用户签名的意图授权。流程为：

创建意图授权（返回 mandateId 和 authorizationUrl)
用户打开 authorizationUrl 授权代理人并签署授权书
使用 mandateId 用于后续付款

POST/api/授权/创建意图

创建新的意图授权。可以在没有JWT（返回指令）或有JWT（直接创建任务）的情况下调用。

curl -X POST https://walletapi.fluxapay.xyz/api/mandates/create-intent \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $AGENT_JWT" \
  -d '{
    "intent": {
      "naturalLanguage": "I plan to spend up to 0.10 USDC to get Polymarket trading recommendations valid for 30 days.",
      "category": "trading_data",
      "currency": "USDC",
      "limitAmount": "100000",
      "validForSeconds": 2592000,
      "hostAllowlist": []
    }
  }'

答复：

{
  "status": "ok",
  "mandateId": "mand_xxxxxxxxxxxxx",
  "authorizationUrl": "https://wallet.fluxapay.xyz/onboard/intent?oid=...",
  "expiresAt": "2024-01-01T00:10:00.000Z",
  "agentStatus": "ready"
}

POST/api/支付/x402V3支付

使用意图授权执行x402 v3付款。

curl -X POST https://walletapi.fluxapay.xyz/api/payment/x402V3Payment \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $AGENT_JWT" \
  -d '{
    "mandateId": "mand_xxxxxxxxxxxxx",
    "scheme": "exact",
    "network": "base",
    "amount": "10000",
    "currency": "USDC",
    "assetAddress": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
    "payTo": "0xFf319473ba1a09272B37c34717f6993b3F385CD3",
    "host": "fluxa-x402-api.gmlgtm.workers.dev",
    "resource": "https://fluxa-x402-api.gmlgtm.workers.dev/polymarket_recommendations_last_1h",
    "description": "Get Polymarket trading recommendations",
    "tokenName": "USD Coin",
    "tokenVersion": "2",
    "validityWindowSeconds": 60
  }'

答复：

{
  "status": "ok",
  "xPaymentB64": "eyJ4NDAyVmVyc2lvbi...",
  "xPayment": {
    "x402Version": 1,
    "scheme": "exact",
    "network": "base",
    "payload": {
      "signature": "0x...",
      "authorization": {
        "from": "0x...",
        "to": "0x...",
        "value": "10000",
        "validAfter": "1700000000",
        "validBefore": "1700000060",
        "nonce": "0x..."
      }
    }
  },
  "paymentRecordId": 123,
  "expiresAt": 1700000060
}

GET/api/mandates/agent/{mandateId}

查询授权状态。

curl -H "Authorization: Bearer $AGENT_JWT" \
  https://walletapi.fluxapay.xyz/api/mandates/agent/mand_xxxxxxxxxxxxx

答复：

{
  "status": "ok",
  "mandate": {
    "mandateId": "mand_xxxxxxxxxxxxx",
    "status": "signed",
    "naturalLanguage": "I plan to spend up to 0.10 USDC...",
    "category": "trading_data",
    "currency": "USDC",
    "limitAmount": "100000",
    "spentAmount": "10000",
    "pendingSpentAmount": "0",
    "remainingAmount": "90000",
    "validFrom": "2024-01-01T00:00:00.000Z",
    "validUntil": "2024-01-31T00:00:00.000Z",
    "hostAllowlist": null,
    "mandateHash": "0x...",
    "signedAt": "2024-01-01T00:05:00.000Z",
    "createdAt": "2024-01-01T00:00:00.000Z",
    "updatedAt": "2024-01-01T00:05:00.000Z"
  }
}

建筑

MCP Server (stdio)
├── Agent ID Management
│   ├── Registration with FluxA Agent ID API
│   └── Local config storage (agent_id, token, jwt)
├── Wallet API Client
│   ├── x402V1Payment calls
│   ├── x402V3Payment calls (intent mandate)
│   ├── Intent Mandate management
│   └── JWT-based authentication
└── MCP Tools
    ├── init_agent_id
    ├── request_x402_payment (v1)
    ├── request_x402_v3_payment (v3 with mandate)
    ├── create_intent_mandate
    ├── get_mandate_status
    ├── request_payout
    ├── get_payout_status
    └── get_agent_status

环境变量

变量	描述	默认值
`FLUXA_DATA_DIR`	数据目录路径	`~/.fluxa-ai-wallet-mcp`
方法1：现有凭据
`AGENT_ID`	代理ID（最高优先级）	-
`AGENT_TOKEN`	代理令牌（最高优先级）	-
`AGENT_JWT`	JWT代理（最高优先级）	-
方法2：注册信息
`AGENT_NAME`	注册代理人名称	-
`CLIENT_INFO`	注册客户信息	-
API终点
`AGENT_ID_API`	代理ID API基本URL	`https://agentid.fluxapay.xyz`
`WALLET_API`	钱包API基础URL	`https://walletapi.fluxapay.xyz`

配置文件

地点： ~/.fluxa-ai-wallet-mcp/config.json

{
  "agentId": {
    "agent_id": "uuid-string",
    "token": "token-string",
    "jwt": "jwt-string",
    "agent_name": "My Agent",
    "client_info": "My Client v1.0",
    "registered_at": "2024-01-01T00:00:00.000Z"
  }
}

JWT代币管理

MCP服务器自动管理JWT令牌生命周期：

自动刷新：

在每次付款请求之前，服务器都会检查JWT是否已过期或即将过期（5分钟内）
如果已过期，则自动调用刷新端点以获取新的JWT
刷新使用 agent_id 和 token （不会过期）

储存：

环境变量：刷新的JWT存储在运行时内存中（不持久）
配置文件：刷新的JWT会自动保存到 ~/.fluxa-ai-wallet-mcp/config.json

手动刷新： 您还可以使用curl手动刷新JWT：

curl -X POST https://agentid.fluxapay.xyz/refresh \
  -H "Content-Type: application/json" \
  -d '{"agent_id": "your-agent-id", "token": "your-token"}'

备注

这是一个无状态MCP服务器，将所有支付逻辑委托给FluxA Wallet API
没有在本地存储或管理私钥
政策管理（限额、审批等）由FluxA Wallet处理
所有付款授权均由FluxA Wallet签署
JWT用于验证所有付款请求
JWT令牌过期时会自动刷新（使用agent_id+令牌）
代理ID注册是每个代理实例的一次性操作

支持的网络

基座（链ID:8453）
基地Sepolia（链号：84532）

支持资产

USDC基准： 0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913

许可证

麻省理工学院

Fluxa AI Wallet MCP

快速接入

详细介绍

FluxA AI钱包MCP

包裹

概述

特性

快速开始

命令行界面

MCP服务器

发展

构建

配置

代理ID配置

MCP工具

1. init_agent_id

2. request_x402_payment

3. request_payout

4. get_payout_status

5. get_agent_status

6. create_intent_mandate

7. get_mandate_status

8. request_x402_v3_payment

工作流程

首次设置

后续付款

API终点

FluxA代理ID API

FluxA钱包API

x402 v3付款（意向委托书）

建筑

环境变量

配置文件

JWT代币管理

备注

支持的网络

支持资产

许可证

目录标签

接入字段

权限和风险

来源信息

继续浏览同类 MCP

1. `init_agent_id`

2. `request_x402_payment`

3. `request_payout`

4. `get_payout_status`

5. `get_agent_status`

6. `create_intent_mandate`

7. `get_mandate_status`

8. `request_x402_v3_payment`