Slug Wallet

Give your terminal AI agent a guarded USDC wallet. It intercepts HTTP 402 paywalls, enforces budget limits, signs payments automatically, and works with any x402 service — today.

Chain: Base mainnet
Token: USDC (0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913)

Why

AI agents hitting paywalled APIs either crash or need raw access to your credit card. Slug Wallet gives them a wallet with hard guardrails:

• $2 daily limit, $0.02 per request — fully configurable

• Domain whitelist — agent can only pay approved services

• Local spend ledger — tracks every payment, persists across restarts

• Plugs into Claude Code, OpenCode, any MCP client — one command

• Works with real x402 services right now — Exa, Otto AI, Tavily, and more

No funds move until the firewall approves the payment. If a request falls outside your limits, the agent gets a clear error and nothing is signed.

Related MCP server: Lightning Enable MCP

Quickstart

1. Connect to your agent

Claude Code:

claude mcp add slug-wallet -s user -- npx slug-wallet-mcp

OpenCode (opencode.json in your project root):

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "slug-wallet": {
      "type": "local",
      "command": ["npx", "slug-wallet-mcp"],
      "enabled": true
    }
  }
}

2. Pick a mode

Dev mode (no real money — for testing):

{
  "env": { "SLUG_WALLET_DEV_SIGNER": "1" }
}

Live mode (real USDC on Base):

{
  "env": {
    "CDP_API_KEY_ID": "your-key-id",
    "CDP_API_KEY_SECRET": "your-key-secret",
    "CDP_WALLET_SECRET": "your-wallet-secret"
  }
}

3. Try it

Ask your agent:

Fetch https://x402.ottoai.services/crypto-news using the slug-wallet tool

The agent will call slug_fetch, Slug Wallet intercepts the 402, checks the firewall, signs the payment, and returns the content. All automatic.

The firewall

Your slug-config.json controls exactly what the wallet is allowed to pay:

{
  "maxUsdPerRequest": 0.02,
  "dailyUsdLimit": 2.00,
  "allowedDomains": ["exa.ai", "*.browserbase.com", "x402.ottoai.services"]
}

The firewall runs before any signature. If a payment is blocked, the agent sees a clear error message explaining why — no funds move, no signature is generated.

Run npx slug-wallet init to create a slug-config.json with safe defaults.

MCP tools

Real x402 services you can use today

These are live services that return HTTP 402 and work with Slug Wallet out of the box:

Add the domain to your allowedDomains and your agent can start paying for these immediately. Browse more at x402scan.com or agentic.market.

Setup

Getting CDP credentials (live mode)

1. Go to portal.cdp.coinbase.com/projects/api-keys

2. Create a Secret API key — copy CDP_API_KEY_ID and CDP_API_KEY_SECRET

3. Go to Wallets → Non-custodial → Security for CDP_WALLET_SECRET

4. Fund your agent wallet with USDC on Base (start with $2)

KYC is required for live accounts. Until KYC is complete, use dev mode.

Environment variables

The server hard-fails at startup if neither CDP credentials nor SLUG_WALLET_DEV_SIGNER=1 is set.

Library usage

Use Slug Wallet programmatically without MCP:

import { createSlugFetch, CdpPaymentSigner } from "slug-wallet";

const signer = new CdpPaymentSigner();
const slugFetch = await createSlugFetch({ signer });

const response = await slugFetch("https://x402.ottoai.services/crypto-news");

Bring your own signer by implementing PaymentSigner:

import type { PaymentSigner, InvoicePayload, PaymentProof } from "slug-wallet";

class MySigner implements PaymentSigner {
  async getAddress(): Promise<string> { ... }
  async signInvoice(invoice: InvoicePayload): Promise<PaymentProof> { ... }
}

The PaymentSigner interface is wallet-agnostic. CdpPaymentSigner (Coinbase CDP) ships built-in, but you can implement it with any EVM wallet provider — Privy, Fireblocks, local private keys, HSMs, etc. The firewall, interceptor, MCP server, and fee settlement layer work identically regardless of where the signature comes from.

Verify

npm run check          # TypeScript build + 67 unit tests
npm run verify:harness # End-to-end interceptor + MockSigner
npm run verify:mcp     # End-to-end MCP subprocess (all 3 tools)

For protocol operators

Slug Wallet supports an on-chain fee settlement layer. When enabled, every payment generates a separate fee authorization that is batched and submitted to a SlugSettlement contract on Base, routing a percentage of each payment to a treasury wallet.

How it works

Agent pays merchant via normal x402 flow
         │
         ├──► Merchant gets paid (normal)
         │
         └──► Slug Wallet signs fee authorization
                  │
                  ▼
           FeeQueue (.slug-wallet/fee-queue.json)
                  │ when total >= $0.05
                  ▼
           Relay (slug-wallet-relay)
                  │
                  ▼
           SlugSettlement.settleFee() on Base
                  │
                  ├──► Fee goes to treasury
                  └──► Settlement event emitted

Configuration

In slug-config.json:

{
  "settlement": {
    "enabled": true,
    "contractAddress": "0x...",
    "feeBps": 50,
    "treasuryAddress": "0x..."
  }
}

• feeBps: Fee in basis points (50 = 0.5%, 500 = 5%)

• contractAddress: Deployed SlugSettlement address on Base

• treasuryAddress: Where fees land (must be set when enabled)

Running the relay

npx slug-wallet-relay

The relay binds to 127.0.0.1 only. Fund the relay wallet with ~$2 of ETH on Base for gas.

Fee queue economics

Fees accumulate locally in .slug-wallet/fee-queue.json. When the total crosses $0.05, the MCP server batches them to the relay, which submits a single on-chain transaction:

50 payments at $0.001 each
  = $0.05 queued fees
  = 1 on-chain tx (~$0.01 gas)
  = $0.04 net to treasury per batch

Settlement contract

The Solidity contract is in contracts/SlugSettlement.sol. Deploy with:

forge create --rpc-url https://mainnet.base.org \
  --private-key $RELAY_PRIVATE_KEY \
  contracts/SlugSettlement.sol:SlugSettlement \
  --constructor-args <treasury-address> <feeBps>

The contract has two functions:

• executePayment() — full payment routing (merchant + fee split in one transaction)

• settleFee() — fee-only settlement (used by the relay in dual-signing mode)

License

MIT