🤖 @evozim/eliza-plugin-x402

Natively Intercept HTTP 402 Paywalls & Autonomously Settle USDC Micropayments on Base L2

@evozim/eliza-plugin-x402 is an official drop-in plugin for Eliza OS (the dominant AI Agent framework maintained by AI16z). It equips autonomous agents with the ability to consume premium pay-per-use APIs and Model Context Protocol (MCP) servers without human intervention.

Whenever an external request returns an HTTP 402 Payment Required response, this plugin intercepts the call, decodes the payment metadata, signs a gasless EIP-3009 TransferWithAuthorization USDC signature, injects it into the headers, and completes the request autonomously.

⚙️ How it Works under the Hood

sequenceDiagram
    participant Agent as Eliza OS Agent
    participant Service as X402Service (Plugin)
    participant API as Premium MCP Server
    participant Escrow as M2MCent Escrow (Base L2)
    
    Agent->>API: 1. Request Tool / API Call
    API-->>Agent: 2. Response: HTTP 402 Payment Required<br/>(Header: payment-required in Base64)
    Note over Service: Intercepts challenge &<br/>decodes metadata
    Service->>Service: 3. Signs EIP-3009 Transfer Auth<br/>(EIP-712 Typed Signature)
    Agent->>API: 4. Retry Request<br/>(Header: payment-signature in Base64)
    API->>Escrow: 5. Relays Signature & Settles USDC Gaslessly
    Escrow-->>API: 6. Settlement Confirmed (Atomic)
    API-->>Agent: 7. Response: HTTP 200 with Tool Output

🚀 Installation

npm install @evozim/eliza-plugin-x402
# or using yarn
yarn add @evozim/eliza-plugin-x402
# or using pnpm
pnpm add @evozim/eliza-plugin-x402

🛠️ Configuration

Configure the agent runtime settings or environment variables (.env):

| Variable | Description | Required | Default | | :--- | :--- | :---: | :--- | | EVM_PRIVATE_KEY | Private key of the agent's EVM wallet. Must hold USDC on Base Mainnet. | Yes | - | | EVM_PROVIDER_URL | Base RPC node endpoint URL. | No | https://mainnet.base.org |

📦 Usage

1. Register the Plugin in your Agent

Import and register the plugin inside your Eliza setup (agent/src/index.ts or character file):

import { x402Plugin } from "@evozim/eliza-plugin-x402";

// In your agent initialization flow:
const runtime = new AgentRuntime({
    // ...other configurations
    plugins: [
        // ...other plugins
        x402Plugin
    ]
});

2. Calling Protected Endpoints programmatically

You can invoke the X402Service anywhere in your custom actions or providers:

import { X402Service, X402ServiceType } from "@evozim/eliza-plugin-x402";

const runAction = async (runtime: IAgentRuntime) => {
    const x402Service = runtime.getService<X402Service>(X402ServiceType.X402 as any);
    
    const result = await x402Service.fetchWithPaywall(
        "https://the-gem-smith-mcp.vercel.app/api/mcp",
        {
            method: "POST",
            body: JSON.stringify({
                jsonrpc: "2.0",
                id: 1,
                method: "tools/call",
                params: {
                    name: "seo_audit",
                    arguments: { url: "https://github.com" }
                }
            })
        }
    );

    if (result.success) {
        console.log("Success! Output:", result.responseBody);
        console.log("Paid Amount:", result.paidAmount, "USDC");
    } else {
        console.error("Failed:", result.error);
    }
};

💬 Natural Language Prompting

The plugin registers a default action X402_CALL_TOOL. If the user asks the agent to query an external endpoint that has a paywall, the agent will execute it:

• User: "Execute the premium audit tool at https://zero-leak-mcp.vercel.app/api/mcp"
• Agent: "⏳ Accessing premium endpoint: https://zero-leak-mcp.vercel.app/api/mcp..."
• Agent: (Signs $0.02 USDC on Base behind the scenes)
• Agent: "✅ Premium tool call successful! 💳 Settle payment: $0.0200 USDC. Response output: { ... }"

🔒 Security & Privacy (Zero-Leak)

• Non-Custodial: The agent signs payments using its own private key. Funds never pass through third-party servers.
• Gasless: The client pays no gas fees. Gas costs for contract interaction are covered by the M2MCent relayer infrastructure. Only the exact USDC fee specified in the HTTP 402 metadata is pulled from the wallet.
• Anti-Replay Protections: Every signature is bound to a unique cryptographically secure 32-byte nonce, preventing double-spending and signature harvesting.

📄 License

MIT License. Created by Evozim / M2MCent.