CLAWD Wallet

Claude's Lightweight Autonomous Wallet for Developers

A unified MCP server providing x402 payments, TAP identity verification, referral onboarding, and domain registration for Claude Code and other MCP clients.

Quick Start (5 minutes)

1. Install

git clone https://github.com/csmoove530/unified-clawd-wallet-mcp.git
cd unified-clawd-wallet-mcp
npm install && npm run build

2. Initialize your wallet

Create a new wallet (key in OS keychain, config at ~/.clawd/config.json):

# Option A: use the CLI (after npm link, see below)
clawd init

# Option B: run init via npm (no global install)
npm run init

To use the clawd command from any directory, run once from the project: npm link.
Initialization is idempotent: running clawd init again does nothing unless you pass --force (which overwrites the existing wallet).

3. Add to Claude Code

Add to ~/.claude.json:

{
  "mcpServers": {
    "clawd-wallet": {
      "command": "node",
      "args": ["/path/to/unified-clawd-wallet-mcp/dist/mcp-server/index.js"],
      "env": {
        "CLAWD_BACKEND_URL": "https://clawd-domain-backend-production.up.railway.app",
        "CLAWD_TAP_MOCK_MODE": "true"
      }
    }
  }
}

Use the real path to dist/mcp-server/index.js. See Canton Network below for Canton setup.

4. Restart Claude Code and Try It

You: "Check my wallet balance"

Claude: [calls x402_check_balance]

{
  "success": true,
  "balance": {
    "address": "0x742d35Cc6634C0532925a3b844Bc9e7595f...",
    "amount": "25.50",
    "currency": "USDC",
    "decimals": 6
  }
}

You now have a working CLAWD Wallet.

---

What Can You Do?

Check Your Balance

You: "What's my USDC balance?"

Returns:

{
  "success": true,
  "balance": {
    "address": "0x742d35Cc6634C0532925a3b844Bc9e7595f...",
    "amount": "25.50",
    "currency": "USDC",
    "decimals": 6
  }
}

Redeem a Referral Code (New Users)

You: "Redeem referral code CLAWD2024"

Returns:

{
  "success": true,
  "code": "CLAWD2024",
  "amount": 15,
  "currency": "USDC",
  "txHash": "0x1234...abcd",
  "recipientAddress": "0x742d35Cc6634C0532925a3b844Bc9e7595f...",
  "explorerUrl": "https://basescan.org/tx/0x1234...abcd",
  "message": "Successfully redeemed $15 USDC! Check your balance with x402_check_balance."
}

Search for a Domain

You: "Search for domains with 'myproject'"

Returns:

{
  "query": "myproject",
  "results": [
    { "domain": "myproject.dev", "available": true, "first_year_price_usdc": "14.99" },
    { "domain": "myproject.xyz", "available": true, "first_year_price_usdc": "4.99" },
    { "domain": "myproject.com", "available": false }
  ]
}

Purchase a Domain

You: "Buy myproject.xyz for John Doe, john@example.com"

Claude will:

1. Call clawd_domain_purchase → Get payment details
2. Call x402_payment_request → Execute USDC payment
3. Call clawd_domain_confirm → Register the domain

Returns:

{
  "success": true,
  "domain": "myproject.xyz",
  "status": "registered",
  "expires": "2027-02-01",
  "nameservers": ["ns1.porkbun.com", "ns2.porkbun.com"]
}

Verify Your Identity (TAP)

You: "Verify my identity for premium merchants"

Returns:

{
  "success": true,
  "status": "verified",
  "agentId": "agent_abc123",
  "identityLevel": "kyc",
  "reputationScore": 50.0,
  "message": "Identity verified at KYC level. Premium merchants will now accept your payments."
}

---

All 27 Tools

Wallet Tools (5)

Tool	Description	Example
x402_payment_request	Pay an x402-enabled service	"Pay $0.01 to https://api.example.com/data"
x402_check_balance	Check USDC balance on Base	"What's my balance?"
x402_get_address	Get wallet address for funding	"What's my wallet address?"
x402_transaction_history	View recent payments	"Show my last 5 transactions"
x402_discover_services	Find x402 services	"Find AI services I can pay for"

Spending Controls (2)

Tool	Description	Example
x402_get_spending_controls	View current spend limits	"Show my spending limits"
x402_update_spending_controls	Update per-transaction and daily limits	"Set my daily limit to $100"

Referral Tools (1)

Tool	Description	Example
x402_redeem_referral	Redeem code for free USDC	"Redeem referral code CLAWD2024"

TAP Identity Tools (4)

Tool	Description	Example
tap_register_agent	Register with TAP registry	"Register my agent as 'My AI Assistant'"
tap_verify_identity	Complete KYC/KYB verification	"Verify my identity at KYC level"
tap_get_status	Check verification status	"What's my TAP status?"
tap_revoke	Remove TAP credentials	"Remove my TAP verification"

Domain Tools (9)

Tool	Description	Example
clawd_domain_search	Search available domains	"Search for domains with 'myapp'"
clawd_domain_purchase	Start domain purchase	"Buy myapp.dev for John Doe"
clawd_domain_confirm	Confirm after payment	(automatic after payment)
clawd_domain_list	List your domains	"Show my domains"
clawd_dns_list	List DNS records	"Show DNS records for myapp.dev"
clawd_dns_create	Create DNS record	"Point myapp.dev to 192.0.2.1"
clawd_dns_delete	Delete DNS record	"Delete the A record for myapp.dev"
clawd_domain_nameservers	Update nameservers	"Use Cloudflare nameservers for myapp.dev"
clawd_domain_auth_code	Get transfer auth code	"Get auth code to transfer myapp.dev"

Canton Network Tools (6)

See Canton Network for setup and usage.

Tool	Description	Example
canton_configure	Create a new party or set existing party ID	"Configure Canton: create a new party with display name test-wallet"
canton_check_balance	Check Canton Coin (CC) balance	"Check my Canton balance"
canton_list_holdings	List all CIP-56 token holdings (UTXOs)	"List my Canton holdings"
canton_get_party_info	Get party ID, validator URL, network	"Show my Canton party info"
canton_transfer	Send CC to another party (needs recipient + amount)	"Transfer 10 CC to <recipient-party-id>"
canton_transaction_history	View send/receive history	"Show my Canton transactions"

---

Common Workflows

New User Onboarding

1. "Redeem referral code CLAWD2024"     → Get $15 USDC
2. "Check my balance"                    → Verify funds arrived
3. "Verify my identity"                  → Enable premium services
4. "Search for domains with 'myproject'" → Find a domain
5. "Buy myproject.xyz"                   → Purchase with USDC

Domain + DNS Setup

1. "Search for coolapp domains"          → Find available options
2. "Buy coolapp.dev for Jane Doe"        → Purchase domain
3. "Point coolapp.dev to 192.0.2.1"      → Create A record
4. "Add www.coolapp.dev as alias"        → Create CNAME record
5. "Show DNS for coolapp.dev"            → Verify configuration

Using x402 Services

1. "Find AI image services"              → Discover services
2. "Generate an image of a sunset"       → Pays automatically via x402
3. "Show my recent transactions"         → Review payments

---

Canton Network

Canton Network tools let you create parties, check balances, list token holdings, transfer Canton Coin (CC), and view transaction history.

Setup

• Local (Splice LocalNet): See CANTON_LOCALNET.md for Docker setup, MCP env configuration, and troubleshooting.
• DevNet (or other non-local): No extra setup. Omit the Canton env vars from your MCP config; the server uses public DevNet endpoints by default.

Canton env vars (only needed for LocalNet or custom deployments):

CANTON_USE_LOCALNET=true                                    # Use local Splice; omit for DevNet
CANTON_VALIDATOR_URL=http://127.0.0.1:2903/api/validator    # LocalNet default
CANTON_LEDGER_API_URL=http://127.0.0.1:2975                 # LocalNet default

Usage

1. Create a party (required first)

You: "Configure Canton: create a new party with display name test-wallet"

Returns:

{
  "success": true,
  "partyId": "test-wallet::12205301d046...",
  "network": "localnet",
  "validatorUrl": "<validator API base, e.g. http://127.0.0.1:2903/api/validator (local) or https://canton-devnet.digitalasset.com/api/v1 (DevNet)>",
  "ledgerApiUrl": "<ledger API URL, e.g. http://127.0.0.1:2975 (local) or https://canton-devnet.digitalasset.com/ledger/v1 (DevNet)>"
}

2. Check balance

You: "Check my Canton balance"

3. List holdings

You: "List my Canton holdings"

4. Transfer

You: "Transfer 10 CC to <recipient-party-id>"

Requires recipient (full party ID) and amount.

5. Transaction history

You: "Show my Canton transactions"

Errors

Error	Cause	Fix
Canton not configured	No party yet	Run canton_configure with displayName to create a party, or with partyId to use existing
The requested resource could not be found	Validator URL wrong	Local: See CANTON_LOCALNET.md. Other: Set CANTON_VALIDATOR_URL in MCP env.
Unexpected token '<', "<!DOCTYPE "...	Hitting HTML instead of API	Validator URL must be the API base, not the UI port (e.g. 2000).
fetch failed / ECONNREFUSED	Canton not running or wrong URL	Local: Start Splice LocalNet. Other: Check validator and ledger URLs.
Invalid recipient party ID format	Bad party ID	Use full party ID (e.g. name::1220...).
Insufficient balance for transfer	Not enough CC	Check balance with canton_check_balance.
No Canton signing key	No private key for transfers	Create party with canton_configure (no partyId) so key is stored, or configure with partyId + privateKey.

---

Error Reference

Wallet Errors

Error	Cause	Fix
Configuration not found	Wallet not initialized	Run clawd init or npm run init (see Quick Start)
No wallet found in keychain	Wallet not initialized or keychain denied	Run clawd init or npm run init; check OS keychain permissions
Insufficient balance	Not enough USDC	Fund wallet or redeem referral code
Transaction failed	Network or gas issue	Retry; check Base network status

Referral Errors

Error	Cause	Fix
Invalid referral code	Code doesn't exist	Check code spelling (case-insensitive)
Code has already been redeemed	Code used up	Request a new code
Code has expired	Past expiration date	Request a new code
This wallet has already redeemed	One redemption per wallet	Cannot redeem again
Treasury has insufficient balance	Treasury empty	Contact support

TAP Errors

Error	Cause	Fix
Not registered	No TAP agent	Call tap_register_agent first
Already verified	Already have verification	Use tap_get_status to check level
Verification failed	KYC/KYB rejected	Contact TAP registry support

Domain Errors

Error	Cause	Fix
Domain not available	Already registered	Try different TLD or name
Invalid domain format	Bad characters in name	Use only a-z, 0-9, hyphens
Payment verification failed	tx_hash invalid	Check transaction completed on Base
Not authorized	Wallet doesn't own domain	Use wallet that purchased domain
Backend connection failed	Backend unreachable	Check CLAWD_BACKEND_URL

Configuration

Environment Variables

MCP Server:

# Required for domain features
CLAWD_BACKEND_URL=https://clawd-domain-backend-production.up.railway.app

# TAP configuration
CLAWD_TAP_REGISTRY=https://tap-registry.visa.com/v1  # Production
CLAWD_TAP_MOCK_MODE=true                              # Demo mode (no real registry)

# Referral system (operators only)
CLAWD_TREASURY_PRIVATE_KEY=0x...                      # Treasury wallet for payouts

Backend (Railway deployment):

PORKBUN_API_KEY=pk1_...          # From porkbun.com/account/api
PORKBUN_SECRET=sk1_...           # From porkbun.com/account/api
TREASURY_ADDRESS=0x...           # Your wallet to receive domain payments
PUBLIC_URL=https://...           # Your Railway deployment URL
DATABASE_URL=sqlite:////tmp/clawd_domains.db  # Railway uses /tmp
ENVIRONMENT=production

Full MCP Configuration

{
  "mcpServers": {
    "clawd-wallet": {
      "command": "node",
      "args": ["/path/to/unified-clawd-wallet-mcp/dist/mcp-server/index.js"],
      "env": {
        "CLAWD_BACKEND_URL": "https://clawd-domain-backend-production.up.railway.app",
        "CLAWD_TAP_MOCK_MODE": "true"
      }
    }
  }
}

For Canton env vars, see Canton Network.

---

Architecture

┌─────────────────────────────────────────────────────────────┐
│  Claude Code / MCP Client                                   │
└─────────────────────────┬───────────────────────────────────┘
                          │ MCP Protocol (stdio)
                          ▼
┌─────────────────────────────────────────────────────────────┐
│  CLAWD Wallet MCP Server (27 tools)                         │
│  ├─ Wallet: balance, payments, history                      │
│  ├─ Referral: code redemption                               │
│  ├─ TAP: identity verification                              │
│  ├─ Domains: search, purchase, DNS                          │
│  └─ Canton: balance, holdings, transfers                    │
└──────────┬──────────────────────┬──────────────┬────────────┘
           │                      │              │
           │ USDC on Base         │ HTTPS        │ Canton Ledger API
           ▼                      ▼              ▼
┌──────────────────┐    ┌────────────────┐    ┌────────────────┐
│  Base Network    │    │ Domain Backend │    │  Canton DevNet │
│  (x402 services) │    │ (Railway)      │    │  (CIP-56)      │
└──────────────────┘    └───────┬────────┘    └────────────────┘
                                │
                                ▼
                        ┌────────────────────┐
                        │  Porkbun API       │
                        └────────────────────┘

---

Security

• Private keys: Stored in OS keychain (macOS Keychain, Windows Credential Manager, Linux libsecret)
• Spend limits: $10/transaction, $50/day (configurable)
• TAP credentials: Stored in ~/.clawd/tap/ with 0600 permissions
• Payment approval: All payments require explicit user approval in Claude Code
• No secrets in code: All credentials via environment variables or keychain

---

Development

# Build
npm run build

# Initialize wallet (creates key in keychain + ~/.clawd/config.json)
npm run init
# Or, after npm link: clawd init
# Use clawd init --force to overwrite an existing wallet

# Watch mode
npm run dev

# Run MCP server directly
node dist/mcp-server/index.js

# Run backend locally
cd backend
python -m venv venv && source venv/bin/activate
pip install -r requirements.txt
uvicorn src.main:app --port 8402 --reload

After Making Code Changes

Any time you modify TypeScript source files, you must rebuild before the changes take effect:

npm run build

Then restart your MCP client (e.g. Claude Code) so it picks up the new server binary.

Tip: Use npm run dev (watch mode) during development to rebuild automatically on save. You still need to restart the MCP client to load the new binary.

---

Deploy Backend to Railway

cd backend
railway login
railway init
railway up

# Set environment variables in Railway dashboard:
# PORKBUN_API_KEY, PORKBUN_SECRET, TREASURY_ADDRESS, PUBLIC_URL, DATABASE_URL

---

Troubleshooting

"Command not found" when starting MCP server

# Rebuild the project
npm run build

# Check the path in your MCP config matches your actual install location
ls /path/to/clawd-wallet/dist/mcp-server/index.js

Tools not appearing in Claude Code

1. Restart Claude Code completely (not just reload)
2. Check MCP config syntax in ~/.claude.json
3. Test server manually: node dist/mcp-server/index.js

Domain purchase stuck at "pending"

1. Check payment transaction completed on BaseScan
2. Verify tx_hash format: 0x + 64 hex characters
3. Check backend logs for Porkbun API errors

"Treasury not configured" on referral

Referral redemption requires a treasury wallet. For operators:

export CLAWD_TREASURY_PRIVATE_KEY=0x...

---

API Reference

See docs/API.md for complete tool input/output schemas.

---

License

Apache-2.0