multiclaw 2.1.0

Desktop x402 payment manager for AI agents

MultiClaw v2.0.0

Get a grip on your agents.

A desktop x402 payment manager for AI agents, by Primer.

Delegate spending authority to agents without sharing private keys. Implements the full AP2 flow: intent, authorization, settlement, and receipt. Accepts direct A2A x402 as well as HTTP x402.

The Problem

AI agents need to pay for things, but giving an agent your private key is dangerous as too many recent examples show. No amount of persuasion is guaranteed to convince a free-willed agent to behave as you ask. MultiClaw sits between your agents and your wallet, enforcing spending policies and requiring human approval when needed.

How It Works

Agent hits paywall → 402 + Payment-Required header
                            ↓
              Agent calls POST /sign with header
                            ↓
         MultiClaw checks policy (daily limit, domain, etc.)
                            ↓
        Auto-approve OR human approval dialog in app
                            ↓
              MultiClaw signs EIP-712 authorization
                            ↓
         Agent retries request with payment header
                            ↓
            Merchant settles via x402 Facilitator
                            ↓
         Agent reports settlement via POST /callback
                            ↓
              MultiClaw verifies on-chain, stores receipt

Any agent framework can integrate via HTTP to localhost:9402 — Claude, GPT, LangChain, custom agents, or any system that can make HTTP requests. Bearer tokens for simplicity, HMAC-SHA256 for production security. The pattern is intentionally simple: detect paywall → request signature → retry with payment → report settlement.

Authorization Controls

• Spend Policies — Daily limits, per-request caps, auto-approve thresholds
• Domain Restrictions — Allowlist/blocklist which merchants can receive payments
• Agent Isolation — Each agent gets unique credentials, cannot access other agents' budgets
• Human Approval — Payments above threshold trigger a dialog in the app
• AP2 Intent Mandates — Signed VDCs document authorization, publishable to AP2 registry for merchant verification

Where Authorization Happens

1. Policy enforcement — SigningService validates each request against the agent's SpendPolicy (daily limits, per-request caps, allowed domains, network restrictions)
2. Human approval — Payments above the auto-approve threshold trigger an ApprovalDialog in the desktop app; user sees agent name, amount, merchant, and policy before approving
3. Cryptographic signature — On approval, MultiClaw signs an EIP-712 authorization; the agent never sees the private key
4. On-chain verification — After settlement, MultiClaw verifies the transaction against blockchain state and records the result

Intent Mandates & Merchant Verification

Each agent can have a signed Intent Mandate — an AP2 VDC documenting:

• Agent identity (code + auth key fingerprint)
• Spending limits (daily, per-request, auto-approve threshold)
• Authorized networks
• Issuing wallet address and signature

Mandates are signed with EIP-191 and can be published to the AP2 Registry. Merchants can query the registry by agent code to verify authorization before accepting payment — confirming the agent is backed by a real human with defined spending limits.

Accountability & Receipts

Every transaction is logged with agent, amount, domain, timestamp, and on-chain tx_hash. Settled payments are verified against the blockchain. AP2-formatted receipts are available via /receipt/{id}.

{
  "type": "AP2Receipt",
  "version": "ap2.primer/v0.1",
  "intent": {
    "agentCode": "XK7M2P",
    "policyName": "standard",
    "approvalMethod": "human"
  },
  "authorization": {
    "walletAddress": "0x742d35Cc6634C0532925a3b844Bc9e7595f...",
    "signedAt": "2025-01-15T14:32:01Z"
  },
  "payment": {
    "amount": "1.50",
    "currency": "USDC",
    "recipient": "0x8ba1f109551bD432803012645Ac136ddd64...",
    "network": "eip155:8453"
  },
  "settlement": {
    "txHash": "0x3a1b2c3d4e5f...",
    "status": "verified",
    "blockNumber": 12847293
  }
}

Failure Handling

When a policy violation occurs (limit exceeded, blocked domain, manual rejection), the agent receives a structured error response with a reason code. This allows the agent to understand why the payment was declined and adjust its behavior — choosing a cheaper option, trying a different merchant, or asking the user for guidance.

The demo video shows this in action: an agent exceeds its daily limit and is forced to reconsider its approach.

Technical Details

• Wallet Security: AES-256-GCM encryption, Argon2id key derivation (64MB, 3 iterations)
• Payment Signing: EIP-712 structured data, EIP-3009 transferWithAuthorization
• Networks: SKALE Base, SKALE Base Sepolia, Base, Base Sepolia
• Protocol Support: v1/v2 HTTP x402 and A2A x402 (direct JSON payloads)
• Auth Modes: Bearer tokens (simple) or HMAC-SHA256 (production)

Architecture

MultiClaw uses a layered core-outwards architecture with clean separation between business logic and user interface:

┌─────────────────────────────────────────────────────────┐
│ CORE LAYER (framework-independent)                      │
│  • MultiClaw coordinator (single source of truth)       │
│  • Services (SigningService, AgentServer)               │
│  • Models (Agent, Policy, Transaction)                  │
│  • Wallet crypto (HD wallets, AES-256-GCM encryption)   │
└─────────────────────────────────────────────────────────┘
                          ▲
                          │ (direct calls or HTTP)
          ┌───────────────┼───────────────┐
          │               │               │
┌─────────▼─────┐  ┌──────▼──────┐  ┌────▼────────┐
│  GUI Mode     │  │  CLI Mode   │  │  Headless   │
│  (PyQt6)      │  │  (terminal) │  │  (daemon)   │
└───────────────┘  └─────────────┘  └─────────────┘

Deployment Modes

GUI Mode (default) — Double-click MultiClaw.exe for the full desktop application with tabs, dialogs, and approval prompts.

CLI Mode — Open a terminal and run:

# Interactive REPL
MultiClaw.exe --cli

# Single commands (scriptable)
MultiClaw.exe agent create MyAgent
MultiClaw.exe policy list
MultiClaw.exe wallet status

Headless Mode — Run MultiClaw.exe --headless for a daemon with no user interface, exposing only the agent API. Useful for servers or remote operation.

Built-in Console

For a hybrid approach, the GUI includes a built-in terminal console (File → Console) that accepts the same commands as the CLI — without leaving the application.

Single Instance

When GUI mode is running, CLI commands connect to the same instance via HTTP — changes made in the terminal appear live in the GUI. This follows the standard daemon pattern used by Docker, Bitcoin Core, and similar tools.

Demo

Video: Watch the demo →

The demo shows the full payment flow from agent request to on-chain settlement, including a failure case where a payment limit is exceeded and the agent is forced to consider a new choice. This video features a prototype version of MultiClaw that doesn't include all current features.

Download

Download MultiClaw.exe →

Download the latest release and run the executable. No installation required.

Scriptable Mode

For automation, use global flags to bypass interactive prompts:

# Auto-confirm destructive actions
MultiClaw.exe policy delete old-policy --yes

# Provide password non-interactively
MultiClaw.exe wallet create mywallet --password "secret"

# Or use environment variable
set MULTICLAW_PASSWORD=secret
MultiClaw.exe wallet open mywallet

Development

Running from source:

git clone https://github.com/primer-systems/multiclaw.git
cd multiclaw
pip install -r requirements.txt

# GUI mode (default)
python src/multiclaw.py

# CLI interactive REPL
python src/multiclaw.py --cli

# Single command (scriptable)
python src/multiclaw.py wallet status
python src/multiclaw.py policy create standard --day 100 --yes

# Headless daemon (no GUI, agent server only)
python src/multiclaw.py --headless

Run tests:

pytest tests/ -v

Links

• Full Documentation
• AP2 Registry
• Test Paywall Builder
• Medium Article

Changelog

v2.0.0

• Added CLI mode with interactive REPL and scriptable single commands
• Added headless daemon mode for server deployments
• Added in-GUI console window (File → Console)
• Single-instance architecture: CLI connects to running GUI via HTTP

v1.0.0

• Initial release