fluxa-agent-payment-fluxa-ai-wallet-mcp

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:

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

MCP Tools

1. init_agent_id

Register a new FluxA Agent ID. This must be called before making payments.

Configuration Methods:

This tool supports two ways to provide registration information:

1. Using environment variables (Method 2 above): If AGENT_NAME and CLIENT_INFO are set, simply call with empty parameters:

   {}
   

2. 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.