FluxA AI Wallet MCP
MCP server for FluxA AI Wallet with x402 (EIP-3009 exact) payment support.
Packages
This repository contains two packages:
에이전트 강화
게시자가 제공하는 설치 방식입니다. PlugMCP 엔드포인트가 아닙니다.
원격 URL인가요, 내 컴퓨터에서 실행하는 명령인가요? 두 설치 방식의 차이
PlugMCP에서 실행
A new server you create. It is not this listing's official endpoint. Use the publisher install when you want their URL and their credentials.
실행게시자 제공
MCP server for FluxA AI Wallet with x402 (EIP-3009 exact) payment support.
This repository contains two packages:
MCP Server of FluxA AI Wallet
| Description |
|---|
| Install |
|---|
@fluxa-pay/fluxa-wallet-mcp | MCP server for AI agent frameworks (Claude Desktop, etc.) | npm install @fluxa-pay/fluxa-wallet-mcp |
@fluxa-pay/fluxa-wallet | Standalone CLI for scripts and automation | npm install -g @fluxa-pay/fluxa-wallet |
This MCP server enables AI agents to make x402 payments using the FluxA Wallet API. It provides a simple interface for agents to register, authenticate, and execute blockchain payments without managing private keys locally.
npm install -g @fluxa-pay/fluxa-wallet
fluxa-wallet status
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
The server stores configuration in ~/.fluxa-ai-wallet-mcp/config.json by default.
You can override the data directory:
export FLUXA_DATA_DIR=/path/to/custom/dir
There are two methods to configure Agent ID via environment variables:
Method 1: Use existing credentials (highest priority)
If you already have Agent ID credentials, set these environment variables:
export AGENT_ID=your-agent-id
export AGENT_TOKEN=your-token
export AGENT_JWT=your-jwt
This method bypasses registration and uses the provided credentials directly.
Method 2: Provide registration information
If you don't have credentials yet, configure registration information:
export AGENT_NAME="Claude Desktop - John's MacBook"
export CLIENT_INFO="Claude Desktop v1.0 on macOS 14.1"
When these are set, calling init_agent_id with empty parameters {} will automatically register using this information.
Priority order:
~/.fluxa-ai-wallet-mcp/config.json)init_agent_id)init_agent_idRegister a new FluxA Agent ID. This must be called before making payments.
Configuration Methods:
This tool supports two ways to provide registration information:
Using environment variables (Method 2 above): If AGENT_NAME and CLIENT_INFO are set, simply call with empty parameters:
{}
Using parameters: If environment variables are not set, provide the information directly:
{
"agent_name": "Claude Desktop - John's MacBook",
"client_info": "Claude Desktop v1.0 on macOS 14.1"
}
Output:
{
"status": "ok",
"agent_id": "uuid-string",
"message": "Agent ID registered successfully"
}
Usage by Agent:
init_agent_id with {}request_x402_paymentGenerate an x402 payment authorization by calling FluxA Wallet API.
Input:
{
"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 is optional. Supply it when the wallet instructs you to complete an external approval flow so the retry can be linked to that approval.
Output:
{
"status": "ok",
"x_payment": "base64-encoded-payment-header",
"x_payment_object": {
"x402Version": 1,
"scheme": "exact",
"network": "base",
"payload": { ... }
}
}
Error (Agent Not Registered):
{
"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..."
}
}
Error (Approval Required):
{
"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."
}
}
request_payoutCreate a payout via FluxA Wallet API.
Notes:
10000 = 0.01 USDC)payout_id is required and must be provided by the caller (idempotency key)Input:
{
"to_address": "0x4eb5b229d43c30fc629d92bf7ed415d6d7f0cabe",
"amount": "10000",
"payout_id": "payout-test-017"
}
Output (Pending Authorization):
{
"payoutId": "payout-test-017",
"status": "pending_authorization",
"txHash": null,
"approvalUrl": "http://localhost:3000/authorize-payout/payout-test-017",
"expiresAt": 1763914398
}
If the payoutId already exists, status might be succeeded and include txHash.
get_payout_statusQuery payout status from the Wallet App public endpoint. This is useful after authorizing a payout in the browser.
Input:
{
"payout_id": "payout-test-017"
}
Output:
{
"payoutId": "payout-test-017",
"status": "succeeded",
"txHash": "0x..."
}
get_agent_statusQuery the current Agent ID configuration status.
Input: None
Output:
{
"configured": true,
"agent_id": "uuid-string",
"agent_name": "Claude Desktop - John's MacBook",
"registered_at": "2024-01-01T00:00:00.000Z"
}
create_intent_mandateCreate an intent mandate for x402 v3 payments. This is the first step in the x402 v3 flow.
Input:
{
"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": []
}
}
Output:
{
"status": "ok",
"mandateId": "mand_xxxxxxxxxxxxx",
"authorizationUrl": "https://wallet.fluxapay.xyz/onboard/intent?oid=...",
"expiresAt": "2024-01-01T00:10:00.000Z",
"agentStatus": "ready"
}
Usage by Agent:
authorizationUrl to authorize and sign the mandatemandateId with request_x402_v3_payment for paymentsget_mandate_statusQuery the status of an intent mandate.
Input:
{
"mandate_id": "mand_xxxxxxxxxxxxx"
}
Output:
{
"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"
}
}
request_x402_v3_paymentSign an x402 v3 payment using an intent mandate. Requires a signed mandateId.
Input:
{
"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"
}
}
Output:
{
"status": "ok",
"xPaymentB64": "eyJ4NDAyVmVyc2lvbi...",
"xPayment": {
"x402Version": 1,
"scheme": "exact",
"network": "base",
"payload": { ... }
},
"paymentRecordId": 123,
"expiresAt": 1700000060
}
Error (Mandate Not Signed):
{
"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."
}
}
Agent calls request_x402_payment without registration
agent_not_registeredAgent collects user information
Agent calls init_agent_id
Agent retries request_x402_payment
Once registered, agents can directly call request_x402_payment without re-registering. The JWT is used to authenticate with FluxA Wallet API.
Base URL: https://agentid.fluxapay.xyz
POST /register
curl -X POST https://agentid.fluxapay.xyz/register \
-H "Content-Type: application/json" \
-d '{
"agent_name": "My Agent",
"client_info": "My Client v1.0"
}'
Response:
{
"agent_id": "uuid-string",
"token": "token-string",
"jwt": "jwt-string"
}
Base URL: https://walletapi.fluxapay.xyz
POST /api/payment/x402V1Payment
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 requires a user-signed intent mandate. The flow is:
mandateId and authorizationUrl)authorizationUrl to authorize agent and sign the mandatemandateId for subsequent paymentsPOST /api/mandates/create-intent
Create a new intent mandate. Can be called without JWT (returns instructions) or with JWT (creates mandate directly).
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": []
}
}'
Response:
{
"status": "ok",
"mandateId": "mand_xxxxxxxxxxxxx",
"authorizationUrl": "https://wallet.fluxapay.xyz/onboard/intent?oid=...",
"expiresAt": "2024-01-01T00:10:00.000Z",
"agentStatus": "ready"
}
POST /api/payment/x402V3Payment
Execute an x402 v3 payment using an intent mandate.
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
}'
Response:
{
"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}
Query mandate status.
curl -H "Authorization: Bearer $AGENT_JWT" \
https://walletapi.fluxapay.xyz/api/mandates/agent/mand_xxxxxxxxxxxxx
Response:
{
"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
Location: ~/.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"
}
}
The MCP server automatically manages JWT token lifecycle:
Automatic Refresh:
agent_id and token (which don't expire)Storage:
~/.fluxa-ai-wallet-mcp/config.jsonManual Refresh: You can also manually refresh the JWT using curl:
curl -X POST https://agentid.fluxapay.xyz/refresh \
-H "Content-Type: application/json" \
-d '{"agent_id": "your-agent-id", "token": "your-token"}'
0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913MIT
MCP Server of FluxA AI Wallet
도구
아직 도구 목록이 없습니다. 원격 서버는 첫 상태 확인 후에 도구 목록이 생깁니다.
FAQ
이 페이지에서 Cursor, Claude Desktop, Claude Code 또는 VS Code용 stdio 설정을 복사합니다. PlugMCP 프록시가 아니라 게시자의 설치 방식을 사용합니다.
이 레코드에는 필수 환경 변수가 등록되어 있지 않습니다.
FluxA AI Wallet은(는) stdio를 통해 로컬에서 실행됩니다.
마지막 확인: 2026-10-28. MCP Server of FluxA AI Wallet