CLAWD Wallet

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: ``json { "success": true, "balance": { "address": "0x742d35Cc6634C0532925a3b844Bc9e7595f...", "amount": "25.50", "currency": "USDC", "decimals": 6 } } ``

Redeem a Referral Code (New Users)

You: "Redeem referral code CLAWD2024"

Returns: ``json { "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: ``json { "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: ``json { "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: ``json { "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: ``json { "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: ``bash export CLAWD_TREASURY_PRIVATE_KEY=0x... ``

---

API Reference

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

---

License

Apache-2.0