x402-firewall

The Autonomous Wallet Dilemma

The modern web is transitioning toward machine-to-machine commerce. APIs that once required monthly SaaS subscriptions or developer credit cards are adopting the x402 (HTTP 402 Payment Required) standard—enabling autonomous AI agents to query APIs and settle micro-transactions per request in USDC on Base L2.

This introduces a dangerous architectural contradiction:

1. If you withhold a wallet from your agent, it remains crippled. It hits payment barriers, gets throttled by free-tier rate limits, and cannot independently acquire real-time research, datasets, or compute.

2. If you equip your agent with a funded private key, you hand full financial custody to a non-deterministic model. A prompt injection attack, a hallucinated contract address, an unvetted dependency, or a runaway while loop can drain the wallet in seconds.

x402-firewall resolves this paradox.

It is an isolated security proxy that sits between your agent runtime (Claude Desktop, Cursor, or custom TypeScript bot) and the external network. The private key remains shielded inside the firewall process. The agent cannot sign arbitrary payloads, cannot approve unlimited ERC-20 allowances, and cannot exceed strict rolling spend limits.

Every outbound financial interaction is deterministically evaluated against spending caps, verified against allowlists, simulated on Base L2 via eth_call, and committed to a local audit trail before a single cryptographic signature is produced.

Related MCP server: MoneySwitch MCP Server

Architecture

The Verification Lifecycle

1. Intercept: The agent issues an outbound request via the x402_fetch MCP tool or SDK wrapper. If the target server responds with HTTP 402 Payment Required, the firewall intercepts the response headers.

2. Deterministic Evaluation: The PolicyEngine evaluates the payment parameters against hard constraints:

   • Per-Call Ceiling: Rejects any request demanding more than the configured maximum (default: $0.05 USDC).

   • Velocity Limits: Checks local rolling spend over the last 1 hour (default: $1.00 USDC) and 24 hours (default: $5.00 USDC).

   • Domain & Contract Validation: Enforces strict domain allowlists with FQDN canonicalization and blocks unapproved EVM contracts.

   • Selector Inspection: Drops dangerous functions such as unconstrained approve, setApprovalForAll, or transferFrom.

3. Pre-Flight Simulation: The EvmSimulator runs an eth_call against Base L2 to simulate the transaction. It validates state changes and verifies that the transaction will not revert or incur gas burn.

4. Isolated Signing: If and only if all policy rules pass, SignerManager signs an off-chain EIP-3009 transferWithAuthorization message in USDC. The authorization is clamped to a strict 24-hour expiration window.

5. Settlement: The signed authorization is injected into the request header (X-PAYMENT) and dispatched to the facilitator. The target API verifies the signature, executes settlement, and returns HTTP 200 OK with the requested payload to the agent.

6. Audit Trail: Every request—whether allowed or blocked—is recorded in a local SQLite database (~/.x402firewall/audit.db) restricted to 0o700 filesystem permissions. Violations trigger an optional real-time webhook alert.

Quickstart

x402-firewall runs in two complementary modes: as a zero-setup MCP Server for desktop AI clients, and as a TypeScript SDK for programmatic applications.

1. Claude Desktop Setup

Add x402-firewall to your Claude Desktop configuration (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

{
  "mcpServers": {
    "x402-firewall": {
      "command": "npx",
      "args": ["-y", "x402-firewall"],
      "env": {
        "NETWORK": "base-sepolia",
        "PRIVATE_KEY": "0xYOUR_AGENT_PRIVATE_KEY",
        "MAX_PER_CALL_USDC": "0.05",
        "MAX_HOURLY_USDC": "1.00",
        "MAX_DAILY_USDC": "5.00",
        "BLOCK_UNLIMITED_APPROVALS": "true"
      }
    }
  }
}

Note: If PRIVATE_KEY is omitted, x402-firewall generates a disposable ephemeral key on launch so you can safely test tools and policy behavior without real funds.

2. Cursor & Antigravity IDE Setup

Add to your project's .cursor/mcp.json or global IDE settings:

{
  "mcpServers": {
    "x402-firewall": {
      "command": "npx",
      "args": ["-y", "x402-firewall"],
      "env": {
        "NETWORK": "base-sepolia",
        "MAX_PER_CALL_USDC": "0.05"
      }
    }
  }
}

3. CLI Inspection

Inspect the firewall status, remaining allowances, and local audit database directly:

# Print current budget, active limits, and rolling spend
npx -y x402-firewall status

# Inspect recent audit logs
npx -y x402-firewall audit

Programmatic TypeScript SDK

For developers orchestrating autonomous agent loops, LangChain pipelines, or custom runtimes:

npm install x402-firewall viem

import { FirewallClient } from 'x402-firewall';

const firewall = new FirewallClient({
  network: 'base-sepolia',
  privateKey: process.env.AGENT_PRIVATE_KEY as `0x${string}`,
  policy: {
    maxPerCallUsdc: 0.05,
    maxHourlyUsdc: 1.00,
    maxDailyUsdc: 5.00,
    allowedDomains: ['api.weather.com', '*.anthropic.com'],
    blockUnlimitedApprovals: true,
  },
});

// Drop-in fetch wrapper that intercepts 402 challenges and handles payments autonomously
const response = await firewall.fetch('https://api.provider.com/v1/forecast');
const data = await response.json();

// Check budget status
const budget = firewall.getBudgetStatus();
console.log(`Remaining hourly allowance: $${budget.remainingHourlyAllowance} USDC`);

// Cleanly release locks and close database
firewall.close();

Threat Matrix & Defense Guarantees

MCP Tools Reference

When connected to an MCP host, x402-firewall registers four tools:

x402_fetch

Performs an HTTP request with automatic 402 interception and settlement.

• url (string, required): The target HTTP URL.

• method (string, optional): HTTP method (GET, POST, PUT, DELETE). Default: GET.

• headers (object, optional): Key-value header pairs.

• body (string, optional): Request payload.

x402_get_budget

Returns real-time spending metrics, active rules, and remaining allowances for the agent wallet.

• No parameters required.

x402_safe_tx

Simulates and executes an allowlisted on-chain transaction on Base L2.

• to (string, required): Destination contract or recipient address.

• data (string, optional): Hex-encoded transaction calldata.

• value (string, optional): Native Wei value.

• amountUsdc (number, optional): USDC amount represented by the transaction.

x402_audit_log

Queries recent audit log entries from the local SQLite store.

• limit (number, optional): Maximum records to return (1-1000). Default: 20.

• status (string, optional): Filter by ALLOWED, BLOCKED, or ALL.

Configuration

All parameters can be configured via environment variables or passed directly to FirewallClient:

Development & Verification

# Install dependencies
npm install

# Run comprehensive test suite (unit tests, security hardening, prompt injection, MCP server)
npm test

# Build TypeScript to dist/
npm run build

License

MIT © x402-firewall Contributors