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.

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

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

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

npx slug-wallet-relay

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

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

License

MIT