llm_wallet – OpenClaw Skill

---

name: llm_wallet description: Manage crypto wallets and make x402 micropayments with USDC stablecoins on Polygon homepage: https://github.com/x402/llm-wallet-mcp metadata: {"openclaw": {"emoji": "💰", "requires": {"bins": ["node"]}, "install": [{"id": "node", "kind": "node", "package": "llm-wallet-mcp", "bins": ["llm-wallet-mcp"], "label": "Install LLM Wallet MCP (node)"}]}}

LLM Wallet - Crypto Wallet & x402 Micropayments

Use llm-wallet commands to manage crypto wallets and make micropayments to paid APIs using USDC stablecoins on Polygon blockchain.

Default Network: Polygon Testnet (polygon-amoy) - safe for testing Facilitator: https://x402-amoy.polygon.technology

Quick Start

# Create wallet
llm-wallet create

# Check balance
llm-wallet balance

# Set spending limits (recommended)
llm-wallet set-limit --per-tx 0.10 --daily 5.00

# View transaction history
llm-wallet history

Wallet Management

Create Wallet

llm-wallet create [--label <name>]

Creates a new HD wallet with encryption. Returns wallet address.

Example:

llm-wallet create --label "agent-wallet"

Import Wallet

llm-wallet import --private-key <key> [--label <name>]

Import existing wallet from private key.

Check Balance

llm-wallet balance

Shows USDC balance and native token balance on current network.

Transaction History

llm-wallet history

View all transactions and payments made from this wallet.

Spending Limits

Set Limits

llm-wallet set-limit --per-tx <amount> --daily <amount>

Set per-transaction and daily spending caps in USDC.

Example:

llm-wallet set-limit --per-tx 0.10 --daily 5.00

Check Limits

llm-wallet get-limits

View current spending limits and daily usage.

x402 Payments

Make Payment

llm-wallet pay <url> [--method GET|POST] [--body <json>]

Make x402 micropayment to a paid API endpoint.

⚠️ IMPORTANT: Always ask user for approval before making payments!

Example:

# Ask user: "I need to make a payment to https://api.example.com/weather. Cost: $0.001 USDC. Approve?"
llm-wallet pay "https://api.example.com/weather?location=London"

Workflow:

1. Check if payment is needed: llm-wallet check-payment <url>
2. Show user: URL, estimated cost, current limits
3. Wait for user approval
4. Execute: llm-wallet pay <url>
5. Confirm completion and show transaction ID

Check Payment (Pre-flight)

llm-wallet check-payment <url>

Checks if wallet can afford payment without executing it.

Dynamic API Registration

Register API

llm-wallet register-api <url> --name <tool_name>

Register a paid API endpoint as a reusable tool.

Example:

llm-wallet register-api "https://api.example.com/weather" --name weather_api

List Registered APIs

llm-wallet list-apis

Show all registered API tools.

Call Registered API

llm-wallet call-api <tool_name> [--params <json>]

Execute a registered API tool. Requires approval if payment needed.

Example:

# Ask user for approval first if cost > 0
llm-wallet call-api weather_api --params '{"location": "London"}'

Unregister API

llm-wallet unregister-api <tool_name>

Remove a registered API tool.

Seller Tools (Advanced)

Verify Payment

llm-wallet verify-payment --header <x-payment-header> --requirements <json>

Verify incoming payment from a buyer (seller-side).

Create Payment Requirements

llm-wallet create-requirements --price <amount> --pay-to <address> --url <resource-url>

Generate payment requirements for a protected resource.

Safety Rules

1. Network Default: Always uses polygon-amoy (testnet) unless configured otherwise
2. Approval Required: Always ask user before making payments
3. Spending Limits: Check limits before payment attempts
4. Transaction Logging: All payments are logged with timestamps
5. Encryption: Wallets are encrypted with AES-256-GCM

Configuration

Environment Variables

• WALLET_ENCRYPTION_KEY - Wallet encryption key (32+ chars, auto-generated if missing)
• WALLET_NETWORK - Network selection (default: polygon-amoy | polygon)
• FACILITATOR_URL - Custom facilitator URL (auto-configured)
• WALLET_MAX_TX_AMOUNT - Per-transaction limit override
• WALLET_DAILY_LIMIT - Daily limit override

Network Info

• Polygon Testnet (Amoy): Chain ID 80002, Facilitator: https://x402-amoy.polygon.technology
• Polygon Mainnet: Chain ID 137, Facilitator: https://x402.polygon.technology

Common Workflows

First Time Setup

# 1. Create wallet
llm-wallet create --label "my-agent"

# 2. Set spending limits
llm-wallet set-limit --per-tx 0.10 --daily 5.00

# 3. Check balance (will be 0 initially)
llm-wallet balance

# 4. Fund wallet with testnet USDC
# User needs to: visit https://faucet.polygon.technology/

Making a Payment

# 1. Pre-check payment
llm-wallet check-payment "https://api.example.com/weather?location=London"

# 2. Show user: URL, cost estimate, current limits
# 3. Ask user: "Approve payment of $0.001 USDC to https://api.example.com/weather?"

# 4. If approved, execute payment
llm-wallet pay "https://api.example.com/weather?location=London"

# 5. Confirm and show transaction ID
llm-wallet history

Registering a Paid API

# 1. Register the API
llm-wallet register-api "https://api.example.com/translate" --name translate_api

# 2. List available APIs
llm-wallet list-apis

# 3. Call the API (with approval)
llm-wallet call-api translate_api --params '{"text": "hello", "to": "es"}'

# 4. View payment in history
llm-wallet history

Error Handling

• Insufficient Balance: Show error and guide user to faucet (testnet) or funding instructions (mainnet)
• Payment Rejected: Transaction reverted, check error message for details
• Limit Exceeded: Show current limits and daily usage, suggest increasing limits
• Network Timeout: Retry with exponential backoff (max 3 attempts)

References

See references/ folder for:

• x402-protocol.md - x402 payment protocol overview
• wallet-setup.md - Detailed wallet setup guide
• examples.md - More usage examples

Notes

• All amounts are in USDC (6 decimals)
• Default network is testnet for safety
• Testnet USDC has no real value
• Always verify network before mainnet usage
• Keep encryption key secure (never share or commit)

LLM Wallet Skill for OpenClaw

Enable OpenClaw agents to own crypto wallets and make x402 micropayments with USDC stablecoins.

What This Skill Does

• Wallet Management: Create, import, and manage HD wallets with encryption
• Check Balance: View USDC and native token balances
• Spending Limits: Set per-transaction and daily spending caps
• x402 Payments: Make micropayments to paid APIs using USDC
• Dynamic APIs: Register paid APIs as reusable tools
• Transaction History: Track all payments and transactions

Installation

Prerequisites

• Node.js 20+
• OpenClaw installed

Install Skill

Option 1: Via ClawHub (Recommended)

clawhub install llm-wallet

Option 2: Manual Installation

# Clone or copy this skill directory to your workspace
cp -r skills/llm-wallet ~/.openclaw/workspace/skills/

# Install MCP server
npm install -g llm-wallet-mcp

Add to PATH

# Add to your shell profile (~/.bashrc, ~/.zshrc)
export PATH="/Users/agada/openclaw/skills/llm-wallet/bin:$PATH"

Quick Start

1. Create Wallet

llm-wallet create --label "my-agent-wallet"

2. Set Spending Limits

llm-wallet set-limit --per-tx 0.10 --daily 5.00

3. Fund Wallet (Testnet)

Visit: https://faucet.polygon.technology/

• Select "USDC" token
• Select "Polygon Amoy" network
• Paste your wallet address
• Request testnet USDC (free)

4. Check Balance

llm-wallet balance

5. Make Payment (with Agent)

User: "What's the weather in London?"

Agent: "I'll check the weather API. Cost: $0.001 USDC. Approve?"

User: "Yes"

Agent executes: llm-wallet pay "https://api.weather.com/current?location=London"

Usage in OpenClaw

Agent Workflow

The agent will automatically:

1. Detect when paid APIs are needed
2. Check cost via llm-wallet check-payment
3. Ask user for approval
4. Execute payment via llm-wallet pay
5. Return API response with transaction confirmation

Example Conversation

User: Translate "hello" to Spanish using a paid translation API

Agent: I found a translation API. The cost is $0.002 USDC.
       Your limits: $0.10 per transaction, $4.98 remaining today.
       Approve this payment?

User: Yes, approved

Agent: [Executes: llm-wallet pay "https://api.translate.com/v1?text=hello&to=es"]
       Translation: "hola"
       Payment completed: 0.002 USDC
       Transaction: 0xabc123...
       Remaining daily limit: $4.978

Commands Available to Agents

Wallet Commands

• llm-wallet create - Create new wallet
• llm-wallet balance - Check USDC balance
• llm-wallet history - View transactions

Payment Commands

• llm-wallet check-payment <url> - Pre-check cost
• llm-wallet pay <url> - Make payment (requires approval!)
• llm-wallet set-limit --per-tx <amt> --daily <amt> - Set limits

API Management

• llm-wallet register-api <url> --name <tool> - Register API
• llm-wallet list-apis - Show registered APIs
• llm-wallet call-api <tool> --params <json> - Call API

Configuration

Environment Variables

# Network (default: polygon-amoy testnet)
export WALLET_NETWORK="polygon-amoy"

# Encryption key (auto-generated if not set)
export WALLET_ENCRYPTION_KEY="your-secure-32-char-key-here"

# Custom facilitator (optional)
export FACILITATOR_URL="https://x402-amoy.polygon.technology"

# Storage directory (default: ~/.llm-wallet)
export STORAGE_DIR="$HOME/.llm-wallet"

OpenClaw Config

Add to ~/.openclaw/config.json5:

{
  "skills": {
    "entries": {
      "llm_wallet": {
        "enabled": true,
        "env": {
          "WALLET_NETWORK": "polygon-amoy",
          "WALLET_ENCRYPTION_KEY": "${WALLET_ENCRYPTION_KEY}"
        }
      }
    }
  }
}

Security

Default Safety Measures

1. Network: Defaults to testnet (polygon-amoy)
2. Approvals: Agent always asks before payments
3. Spending Limits: Per-transaction and daily caps
4. Encryption: Wallets encrypted with AES-256-GCM
5. Logging: All transactions logged with timestamps

Best Practices

• Start with testnet (polygon-amoy)
• Set conservative spending limits
• Review transaction history regularly
• Never commit encryption keys to git
• Test thoroughly before mainnet use

Networks

Polygon Testnet (Amoy) - Default

• Chain ID: 80002
• Facilitator: https://x402-amoy.polygon.technology
• USDC: 0x41E94Eb019C0762f9Bfcf9Fb1E58725BfB0e7582
• Faucet: https://faucet.polygon.technology/
• Safe for testing (no real money)

Polygon Mainnet

• Chain ID: 137
• Facilitator: https://x402.polygon.technology
• USDC: 0x3c499c542cEF5E3811e1192ce70d8cC03d5c3359
• ⚠️ Real money - use with caution

Documentation

• SKILL.md - Complete command reference
• references/x402-protocol.md - x402 payment protocol overview
• references/wallet-setup.md - Detailed setup guide
• references/examples.md - Usage examples and workflows

Troubleshooting

Command Not Found

# Check if llm-wallet is in PATH
which llm-wallet

# If not, add to PATH:
export PATH="/Users/agada/openclaw/skills/llm-wallet/bin:$PATH"

MCP Server Not Found

npm install -g llm-wallet-mcp
# or
npx llm-wallet-mcp

Insufficient Balance

# Check balance
llm-wallet balance

# Fund via testnet faucet
# Visit: https://faucet.polygon.technology/

Payment Failed

# Check limits
llm-wallet get-limits

# Check history for errors
llm-wallet history

# Verify network configuration
echo $WALLET_NETWORK  # Should be "polygon-amoy"

Examples

See references/examples.md for complete workflows including:

• First time user setup
• Making payments with approval
• Registering and using paid APIs
• Monitoring usage and limits
• Error handling scenarios

Support

• GitHub: https://github.com/x402/llm-wallet-mcp
• x402 Protocol: https://www.x402.org/
• OpenClaw Docs: https://docs.openclaw.ai/
• ClawHub: https://clawhub.com/

License

MIT License - See LICENSE file for details

Contributing

Contributions welcome! Please:

1. Test on polygon-amoy testnet
2. Include examples in PR description
3. Update documentation as needed
4. Follow OpenClaw skill conventions

Version

v1.0.0 - Initial release with core wallet and x402 payment functionality