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"]
}

Rule	What it does
maxUsdPerRequest	Blocks any single payment above this amount
dailyUsdLimit	Blocks all payments once the daily total is hit
allowedDomains	Blocks payments to any domain not in the list (supports *.example.com wildcards)

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

Tool	What it does
slug_fetch	Make an HTTP request, auto-paying any 402 within firewall limits
get_wallet_address	Returns the signing wallet address
get_daily_spend	Returns { spentUsd, limitUsd, remainingUsd, pendingFeesUsd, pendingFeeCount }

---

Real x402 services you can use today

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

Service	URL	Price	What it does
Otto AI	https://x402.ottoai.services/crypto-news	$0.001	Real-time crypto market news with sentiment
Otto AI	https://x402.ottoai.services/trending-altcoins	$0.001	Top 3 trending altcoins
Exa Search	https://api.exa.ai/search	$0.007	AI web search
Tavily	https://x402.tavily.com/search	$0.01	Advanced web search
twit.sh	https://x402.twit.sh/tweets/search	$0.006	Twitter/X tweet search
CoinGecko	https://pro-api.coingecko.com/api/v3/x402/onchain/search/pools	$0.01	Onchain DEX pool data
Anchor	https://api.anchor-x402.com/v1/price/token	$0.001	Token price lookup

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

Variable	Required	Description
CDP_API_KEY_ID	Live mode	Coinbase CDP API key ID
CDP_API_KEY_SECRET	Live mode	Coinbase CDP API key secret
CDP_WALLET_SECRET	Live mode	Coinbase CDP wallet secret
SLUG_WALLET_DEV_SIGNER	Dev mode	Set to 1 for fake signatures (no real payments)
SLUG_WALLET_CONFIG_PATH	Optional	Path to slug-config.json (default: ./slug-config.json)

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

<details> <summary>Setting up the fee settlement layer (optional)</summary>

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

Variable	Required	Description
SLUG_RELAY_PRIVATE_KEY	Yes	Private key of a Base wallet with ETH for gas
SLUG_RELAY_AUTH_TOKEN	Yes	Secret token shared with the MCP server
SLUG_RELAY_PORT	Optional	Port to listen on (default: 4022)
SLUG_WALLET_RELAY_URL	MCP server	URL of the relay (e.g. http://127.0.0.1:4022)

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)

</details>

---

License

MIT