npm package: @lucid-agents/opencode-x402-plugin
Description: OpenCode auth plugin for x402 payment protocol - sign permits with your wallet
Author: Daydreams AI
Latest version: 0.1.12

# opencode-x402-auth

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

## Installation

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

```

## Quick Start

### 1. Configure OpenCode

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

```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

```bash
# 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

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

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

### Types

```typescript
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

```bash
# 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