opencode-x402-auth

OpenCode auth plugin for the x402 payment protocol. Sign ERC-2612 permits with your wallet to pay for LLM inference.

Installation

# npm
npm install -g @lucid-agents/opencode-x402-plugin

Quick Start

1. Configure OpenCode

Add the plugin to your ~/.config/opencode/opencode.json:

{
  "$schema": "https://opencode.ai/config.json",
  "plugin": ["@lucid-agents/opencode-x402-plugin"],
  "provider": {
    "x402": {
      "npm": "@ai-sdk/openai-compatible",
      "name": "x402 Router",
      "options": {
        "baseURL": "http://localhost:8080/v1"
      },
      "models": {
        "openai:gpt-4": { "name": "GPT-4" },
        "anthropic:claude-sonnet-4-20250514": { "name": "Claude Sonnet 4" }
      }
    }
  },
  "model": "x402/anthropic:claude-sonnet-4-20250514"
}

2. Connect Your Wallet

In OpenCode, run /connect and select "x402":

1. Choose "Connect Wallet (Private Key)"
2. Enter your wallet's private key (0x-prefixed)
3. The plugin will sign permits automatically

3. Start Coding

That's it! The plugin automatically:

• Fetches router configuration
• Signs ERC-2612 permits for each request
• Injects the PAYMENT-SIGNATURE header

How It Works

OpenCode → Plugin (signs permit) → x402 Router → LLM Provider
                ↓
         Your Wallet (ERC-2612 permit)

1. You make a request - OpenCode sends a chat message
2. Plugin intercepts - Before the request reaches the router
3. Permit is signed - Using your wallet's private key (EIP-712)
4. Header is injected - PAYMENT-SIGNATURE: <base64-encoded-permit>
5. Router processes - Validates permit, forwards to provider
6. Response streams - Back through OpenCode to you
7. Payment tracked - Router tracks cost asynchronously

Configuration Options

Via /connect in OpenCode

| Option | Description | |--------|-------------| | Connect Wallet | Enter your private key (stored locally) | | Configure Router URL | Set custom router endpoint | | Set Permit Cap | Maximum USDC per permit session |

Environment Variables

# Optional: Override router URL
export X402_ROUTER_URL="https://router.example.com"

# Optional: Override permit cap (in USDC)
export X402_PERMIT_CAP="50"

Supported Networks

| Network | CAIP-2 ID | USDC Contract | |---------|-----------|---------------| | Base Mainnet | eip155:8453 | 0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913 | | Base Sepolia | eip155:84532 | 0x036CbD53842c5426634e7929541eC2318f3dCF7e | | Ethereum Mainnet | eip155:1 | 0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48 |

Security

Important security considerations:

1. Use a dedicated wallet - Create a wallet specifically for AI spending
2. Fund minimally - Only keep what you're willing to spend
3. Set low caps - Start with $1-10 permit caps
4. Private key storage - Stored locally in OpenCode's auth store (~/.local/share/opencode/auth.json)

Never use your main wallet's private key. Create a burner wallet and fund it with small amounts.

API Reference

Plugin Export

import { X402AuthPlugin } from "@lucid-agents/opencode-x402-plugin";

// The plugin is auto-loaded by OpenCode
// Manual usage:
const plugin = await X402AuthPlugin({ client });

Types

interface X402Auth {
  type: "wallet" | "manual";
  privateKey?: string;
  routerUrl?: string;
  permitCap?: string;  // In token units (6 decimals for USDC)
  network?: string;    // CAIP-2 format
}

Troubleshooting

"402 Payment Required"

The permit wasn't accepted. Check:

1. Wallet has sufficient USDC balance
2. Router is running and accessible
3. Permit cap is high enough for the request

"Failed to fetch router config"

Router endpoint unreachable. Verify:

1. Router URL is correct
2. Router is running: curl http://localhost:8080/health

"Invalid private key format"

Private key must be:

• 66 characters (including 0x prefix)
• Valid hex string
• Example: 0x1234567890abcdef... (64 hex chars after 0x)

Development

# Clone the repo
git clone https://github.com/daydreamsai/router.git
cd router/packages/opencode-x402-auth

# Install dependencies
bun install

# Build
bun run build

# Type check
bun tsc --noEmit

License

MIT