FluxA AI Wallet MCP

MCP server for FluxA AI Wallet with x402 (EIP-3009 exact) payment support.

Packages

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`

Overview

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.

Features

Agent ID Management: Register and manage FluxA Agent IDs
x402 Payment Support: Generate EIP-3009 payment authorizations via FluxA Wallet API
Automatic JWT Refresh: Automatically refreshes expired JWT tokens before payments
No Local Key Management: All signing is handled by FluxA Wallet (no local private keys)
Policy Management: Policies are managed remotely by FluxA Wallet
Environment Variable Support: Configure via env vars or config file

Quick Start

CLI

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

MCP Server

npm install
npm run build
npm start

Development

npm run dev

Build

# Build MCP server only
npm run build

# Build CLI bundle only
npm run build:wallet

# Build both
npm run build:all

Configuration

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

Agent ID Configuration

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:

Method 1 environment variables (AGENT_ID + AGENT_TOKEN + AGENT_JWT)
Config file (~/.fluxa-ai-wallet-mcp/config.json)
Method 2 environment variables (requires calling init_agent_id)
Manual registration (requires user input)

MCP Tools

1. `init_agent_id`

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:

If environment variables are configured (Method 2), simply call init_agent_id with {}
Otherwise:
1. Choose a meaningful agent name (e.g., "Claude Desktop - User's Computer")
2. Provide client information (e.g., "Claude Desktop v1.0 on macOS")
3. Call this tool with the collected parameters

2. `request_x402_payment`

Generate 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."
  }
}

3. `request_payout`

Create a payout via FluxA Wallet API.

Notes:

Amount must be provided in smallest units (e.g., USDC has 6 decimals, so 10000 = 0.01 USDC)
Network, currency, and asset are hardcoded to Base mainnet USDC inside MCP (no need to pass them)
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.

4. `get_payout_status`

Query 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..."
}

5. `get_agent_status`

Query 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"
}

6. `create_intent_mandate`

Create 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:

Call this tool with the intent parameters
Ask the user to open authorizationUrl to authorize and sign the mandate
Use the mandateId with request_x402_v3_payment for payments

7. `get_mandate_status`

Query 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"
  }
}

8. `request_x402_v3_payment`

Sign 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."
  }
}

Workflow

First-Time Setup

Agent calls request_x402_payment without registration
- Server returns error with code agent_not_registered
- PMC instructions guide the agent to register
Agent collects user information
- Generate meaningful agent name based on environment
- Prepare client info string
Agent calls init_agent_id
- Server registers with FluxA Agent ID API
- Returns agent_id, token, and JWT
- Configuration is saved automatically
Agent retries request_x402_payment
- Server calls FluxA Wallet API with JWT
- Returns signed payment authorization
- Agent adds X-Payment header and retries the HTTP request

Subsequent Payments

Once registered, agents can directly call request_x402_payment without re-registering. The JWT is used to authenticate with FluxA Wallet API.

API Endpoints

FluxA Agent ID 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"
}

FluxA Wallet API

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 Payment (Intent Mandate)

x402 v3 requires a user-signed intent mandate. The flow is:

Create an intent mandate (returns mandateId and authorizationUrl)
User opens authorizationUrl to authorize agent and sign the mandate
Use mandateId for subsequent payments

POST /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"
  }
}

Architecture

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

Environment Variables

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`	Agent JWT (highest priority)	-
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`

Configuration File

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"
  }
}

JWT Token Management

The MCP server automatically manages JWT token lifecycle:

Automatic Refresh:

Before each payment request, the server checks if the JWT is expired or expiring soon (within 5 minutes)
If expired, automatically calls the refresh endpoint to get a new JWT
Refresh uses the agent_id and token (which don't expire)

Storage:

Environment variables: Refreshed JWT is stored in runtime memory (not persisted)
Config file: Refreshed JWT is automatically saved to ~/.fluxa-ai-wallet-mcp/config.json

Manual 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"}'

Notes

This is a stateless MCP server that delegates all payment logic to FluxA Wallet API
No private keys are stored or managed locally
Policy management (limits, approvals, etc.) is handled by FluxA Wallet
All payment authorizations are signed by FluxA Wallet
The JWT is used to authenticate all payment requests
JWT tokens are automatically refreshed when expired (using agent_id + token)
Agent ID registration is a one-time operation per agent instance

Supported Networks

Base (chainId: 8453)
Base Sepolia (chainId: 84532)

Supported Assets

USDC on Base: 0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913

License

MIT

FluxA AI Wallet MCP

Packages

Overview

Features

Quick Start

CLI

MCP Server

Development

Build

Configuration

Agent ID Configuration

MCP Tools

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

Workflow

First-Time Setup

Subsequent Payments

API Endpoints

FluxA Agent ID API

FluxA Wallet API

x402 v3 Payment (Intent Mandate)

Architecture

Environment Variables

Configuration File

JWT Token Management

Notes

Supported Networks

Supported Assets

License

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`