
MCP Server of FluxA AI Wallet
MCP Server of FluxA AI Wallet
·
MCP server for FluxA AI Wallet with x402 (EIP-3009 exact) payment support.
This repository contains two packages:
| Package | 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 connect --client "My AI Client"
# Show authorization_url, then wait for browser approval:
fluxa-wallet connect-status --wait 100npm install
npm run build
npm startnpm run dev# Build MCP server only
npm run build
# Build CLI bundle only
npm run build:wallet
# Build both
npm run build:allThe 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/dirCLI/MCP 0.6.0 adds browser connection as the default setup. Use connect_wallet
and get_wallet_connection in MCP. No persistent identity is required before
connecting: the owner chooses an existing Agent ID or creates one in the wallet.
Check fluxa-wallet status first: configured:true with wallet_linked:true
means ready; continue the task without a connection link or polling. Token refresh and wallet access are independent.
connect checks a pending request first or calls AgentDID refresh. Successful refresh
returns connected:true, including when the wallet has yet to authorize this agent.
status reports wallet_status from the wallet status endpoint and supplies the
wallet-selected link when needed. Retry unknown status. When connect returns
an authorization URL, use connect-status to wait or rerun connect to claim.
If the client knows its ID, send agent_id (connect --agent-id <id>); the page
locks that identity and rejects a different owner account. Empty accounts create
an identity named after the requester only when the owner approves.
The request, approval link, and credential claim/retry windows each default to
3 hours (10800 seconds). Token validity is separately chosen by the owner.
The CLI omits validity by default: the server suggests 180 days for local
execution or macOS/Windows, and 7 days for cloud/VM/container or other environments.
Only send --validity 1h|24h|7d|1mo|180d|1y when the user explicitly specifies
a duration; the owner can still change it on the page. Use --reconnect to
request a new token when credentials are already valid.
The page displays requester name and execution environment,
without a comparison code. Credentials and login JWTs retain their existing
shape; consumers do not need session-aware authentication.
token_expired/token_revoked returns reconnect_required: true. Reconnect to
the same Agent ID, never re-run init as an automatic recovery step. Network
errors are retryable and do not require a new identity. Existing init and
link-wallet remain supported for explicit registration and legacy workflows.
The environment configuration methods below remain supported; injected credentials take priority over saved files and must be updated/removed if stale.
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-jwtThis method bypasses registration and uses the provided credentials directly.
AGENT_ID and AGENT_TOKEN are sufficient: AGENT_JWT is an optional cache.
status/connect refresh an absent or expired JWT automatically with that token;
injected credentials remain authoritative and refreshed JWTs stay in memory.
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_xxxxxxxxxxxxxResponse:
{
"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| Variable | Description | Default |
|---|---|---|
FLUXA_DATA_DIR | Data directory path | ~/.fluxa-ai-wallet-mcp |
| Method 1: Existing Credentials | ||
AGENT_ID | Agent ID (highest priority) | - |
AGENT_TOKEN | Agent token (highest priority) | - |
AGENT_JWT | Optional cached JWT for injected credentials | - |
| Method 2: Registration Info | ||
AGENT_NAME | Agent name for registration | - |
CLIENT_INFO | Client info for registration | - |
| API Endpoints | ||
AGENT_ID_API | Agent ID API base URL | https://agentid.fluxapay.xyz |
WALLET_API | Wallet API base URL | https://walletapi.fluxapay.xyz |
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
This repo does not document an install step we could read. Check the README on GitHub.
Paste this prompt into your agent. It reads this page and does the setup for you.
Read https://aiagentslisting.com/mcp/fluxa-ai-wallet-mcp to learn what the "FluxA AI Wallet MCP" MCP server does and how to install it. Add it to my coding agent's MCP configuration as documented on that page, then confirm the server connects and list the tools it exposes.Agents can also browse this directory over MCP at https://aiagentslisting.com/api/mcp
This server doesn't publish a machine-readable tool manifest, and it doesn't expose a public endpoint we could ask. Connect the server locally to see what it exposes.
We could not run this server: it ships no npx package for our sandbox and no public endpoint. The four checks that need a live server are left out, and the grade tops out at B until one exists.
Maintain this server? Claiming proves you own the listing and earns the last 4 points.
Claim this listingPaste this line near the top of your repository's README. The badge always renders the current score.
[](https://aiagentslisting.com/mcp/fluxa-ai-wallet-mcp)Nothing comparable is listed yet.
No tagged releases on record.
Connect to the AI Agents Listing MCP server at https://aiagentslisting.com/api/mcp using the HTTP transport and complete the sign-in when it asks. Then call the submit_review tool for the listing "fluxa-ai-wallet-mcp" with a rating from 1 to 5 and a short note on what worked and what did not.No reviews yet
Be the first to share your experience with this tool.
One email a week. New agents, MCP servers and skills, and what is actually getting traction.