agentic-x402 0.1.2 → 0.2.1

package/README.md

@@ -27,20 +27,26 @@ x402 --version
 
 ### Configure
 
-Set your wallet private key (required):
+Run the interactive setup to create a new wallet:
 
 ```bash
-export EVM_PRIVATE_KEY=0x...your_private_key...
+x402 setup
 ```
 
-Or create a persistent config file:
+This will:
+1. Generate a new wallet (recommended) or accept an existing key
+2. Save configuration to `~/.x402/.env`
+3. Display your wallet address for funding
+4. Show your private key for backup
+
+**Back up your private key immediately!** See [Backup](#backup-your-private-key) below.
+
+#### Manual Configuration
+
+Alternatively, set the environment variable directly:
 
 ```bash
-mkdir -p ~/.x402
-cat > ~/.x402/.env << 'EOF'
-EVM_PRIVATE_KEY=0x...your_private_key...
-X402_NETWORK=mainnet
-EOF
+export EVM_PRIVATE_KEY=0x...your_private_key...
 ```
 
 ### Development / Local Install
@@ -56,24 +62,38 @@ cp config/example.env .env
 ## Quick Start
 
 ```bash
-# 1. Configure your wallet
-export EVM_PRIVATE_KEY=0x...your_private_key...
+# 1. Create a wallet
+x402 setup
 
-# 2. Check balance
+# 2. Fund your wallet with USDC on Base (send to the address shown)
+
+# 3. Check balance
 x402 balance
 
-# 3. Pay for a resource
+# 4. Pay for a resource
 x402 pay https://api.example.com/paid-endpoint
 
-# 4. Fetch with auto-payment
+# 5. Fetch with auto-payment
 x402 fetch https://api.example.com/data --json
 
-# 5. Create a payment link (requires x402-links-server)
+# 6. Create a payment link (requires x402-links-server)
 x402 create-link --name "My API" --price 1.00 --url https://api.example.com/premium
 ```
 
 ## Commands
 
+### setup — Create or Configure Wallet
+
+Interactive setup that generates a new wallet or accepts an existing private key. Saves configuration to `~/.x402/.env`.
+
+```bash
+x402 setup
+```
+
+**Security:** If you choose to use an existing private key, you'll see a warning. We recommend using a **dedicated wallet** with limited funds for automated agents.
+
+---
+
 ### balance — Check Wallet Balances
 
 Show your wallet address, USDC balance (for payments), and ETH balance (for gas). Warns if either balance is low.
@@ -223,6 +243,7 @@ Config is loaded from these locations (in order of priority):
 
 | Category | Command | Description |
 |----------|---------|-------------|
+| **Setup** | `setup` | Create or configure your x402 wallet |
 | **Info** | `balance` | Check wallet USDC and ETH balances |
 | **Payments** | `pay <url>` | Pay for an x402-gated resource (verbose output) |
 | **Payments** | `fetch <url>` | Fetch with auto-payment (pipe-friendly `--json`/`--raw`) |
@@ -244,6 +265,50 @@ x402 fetch https://api.example.com/data --json
 x402 fetch https://api.example.com/data --raw
 ```
 
+## Backup Your Private Key
+
+Your private key is stored in `~/.x402/.env`. **If lost, your funds cannot be recovered.**
+
+### Recommended Backup Methods
+
+1. **Password Manager** (Recommended)
+   - Store in 1Password, Bitwarden, or similar
+   - Create a secure note with your private key
+
+2. **Encrypted File**
+   ```bash
+   gpg -c ~/.x402/.env
+   # Store the encrypted .env.gpg file securely
+   ```
+
+3. **Paper Backup** (for larger amounts)
+   - Write down the private key
+   - Store in a safe or safety deposit box
+
+### View Your Private Key
+
+```bash
+cat ~/.x402/.env | grep EVM_PRIVATE_KEY
+```
+
+### Recovery
+
+```bash
+mkdir -p ~/.x402
+echo "EVM_PRIVATE_KEY=0x...your_backed_up_key..." > ~/.x402/.env
+chmod 600 ~/.x402/.env
+x402 balance  # verify
+```
+
+## Security Best Practices
+
+- **Use a dedicated wallet** — Never use your main wallet with automated agents
+- **Limit funds** — Only transfer what you need for payments
+- **Set payment limits** — Configure `X402_MAX_PAYMENT_USD` to cap exposure
+- **Test first** — Use `X402_NETWORK=testnet` before mainnet
+- **Protect the config** — Keep `~/.x402/.env` with 600 permissions
+- **Never share** — Your private key gives full access to your wallet
+
 ## License
 
 MIT

package/SKILL.md

@@ -5,7 +5,7 @@ license: MIT
 compatibility: Requires Node.js 20+, network access to x402 facilitators and EVM chains
 metadata:
   author: monemetrics
-  version: "0.1.0"
+  version: "0.2.1"
 allowed-tools: Bash(x402:*) Bash(npm:*) Read
 ---
 
@@ -17,6 +17,7 @@ Pay for x402-gated APIs and content using USDC on Base. This skill enables agent
 
 | Command | Description |
 |---------|-------------|
+| `x402 setup` | Create or configure wallet |
 | `x402 balance` | Check USDC and ETH balances |
 | `x402 pay <url>` | Pay for a gated resource |
 | `x402 fetch <url>` | Fetch with auto-payment |
@@ -38,20 +39,33 @@ x402 --version
 
 ## Setup
 
-Configure your wallet private key (required):
+Run the interactive setup to create a new wallet:
+
+```bash
+x402 setup
+```
+
+This will:
+1. Generate a new wallet (recommended) or accept an existing key
+2. Save configuration to `~/.x402/.env`
+3. Display your wallet address for funding
+
+**Important:** Back up your private key immediately after setup!
+
+### Manual Configuration
+
+Alternatively, set the environment variable directly:
 
 ```bash
 export EVM_PRIVATE_KEY=0x...your_private_key...
 ```
 
-Or create a persistent config file:
+Or create a config file:
 
 ```bash
 mkdir -p ~/.x402
-cat > ~/.x402/.env << 'EOF'
-EVM_PRIVATE_KEY=0x...your_private_key...
-X402_NETWORK=mainnet
-EOF
+echo "EVM_PRIVATE_KEY=0x..." > ~/.x402/.env
+chmod 600 ~/.x402/.env
 ```
 
 Verify setup:
@@ -299,12 +313,53 @@ Ensure your wallet has funds on the correct network:
 - `X402_NETWORK=mainnet` → Base mainnet
 - `X402_NETWORK=testnet` → Base Sepolia
 
-## Security Notes
+## Backup Your Private Key
+
+Your private key is stored in `~/.x402/.env`. If lost, your funds cannot be recovered.
+
+### Recommended Backup Methods
+
+1. **Password Manager** (Recommended)
+   - Store in 1Password, Bitwarden, or similar
+   - Create a secure note with your private key
+   - Tag it for easy retrieval
+
+2. **Encrypted File**
+   ```bash
+   # Encrypt with GPG
+   gpg -c ~/.x402/.env
+   # Creates ~/.x402/.env.gpg - store this backup securely
+   ```
+
+3. **Paper Backup** (for larger amounts)
+   - Write down the private key
+   - Store in a safe or safety deposit box
+   - Never store digitally unencrypted
+
+### View Your Private Key
+
+```bash
+cat ~/.x402/.env | grep EVM_PRIVATE_KEY
+```
+
+### Recovery
+
+To restore from backup:
+```bash
+mkdir -p ~/.x402
+echo "EVM_PRIVATE_KEY=0x...your_backed_up_key..." > ~/.x402/.env
+chmod 600 ~/.x402/.env
+x402 balance  # verify
+```
+
+## Security Best Practices
 
-- Never share your private key
-- Start with testnet to verify setup
-- Set reasonable payment limits
-- Review payment amounts before confirming
+- **Use a dedicated wallet** — Never use your main wallet with automated agents
+- **Limit funds** — Only transfer what you need for payments
+- **Set payment limits** — Configure `X402_MAX_PAYMENT_USD` to cap exposure
+- **Test first** — Use `X402_NETWORK=testnet` with test tokens before mainnet
+- **Protect the config** — `~/.x402/.env` has 600 permissions; keep it that way
+- **Never share** — Your private key gives full access to your wallet
 
 ## Links
 

package/bin/cli.ts

@@ -11,10 +11,17 @@ const scriptsDir = resolve(__dirname, '../scripts');
 interface Command {
   script: string;
   description: string;
-  category: 'info' | 'payments' | 'links';
+  category: 'setup' | 'info' | 'payments' | 'links';
 }
 
 const commands: Record<string, Command> = {
+  // Setup commands
+  setup: {
+    script: 'commands/setup.ts',
+    description: 'Create or configure your x402 wallet',
+    category: 'setup',
+  },
+
   // Info commands
   balance: {
     script: 'commands/balance.ts',
@@ -53,6 +60,9 @@ x402 - Agent skill for x402 payments
 
 Usage: x402 <command> [arguments]
 
+Setup:
+  setup               Create or configure your x402 wallet
+
 Info Commands:
   balance             Check wallet USDC and ETH balances
 
@@ -68,26 +78,18 @@ Options:
   -h, --help          Show this help
   -v, --version       Show version
 
-Environment Variables:
-  EVM_PRIVATE_KEY       Wallet private key (required)
-  X402_NETWORK          Network: mainnet or testnet (default: mainnet)
-  X402_MAX_PAYMENT_USD  Max payment limit in USD (default: 10)
-  X402_FACILITATOR_URL  Custom facilitator URL
-  X402_LINKS_API_URL    x402-links-server URL (for link commands)
-  X402_LINKS_API_KEY    API key for x402-links-server
-
-Examples:
-  x402 balance
-  x402 pay https://api.example.com/data
-  x402 fetch https://api.example.com/resource --json
-  x402 create-link --name "Guide" --price 5.00 --url https://mysite.com/guide
+Getting Started:
+  1. Run "x402 setup" to create a new wallet
+  2. Fund your wallet with USDC on Base
+  3. Run "x402 balance" to verify
+  4. Use "x402 pay <url>" to pay for resources
 
 For command-specific help: x402 <command> --help
 `);
 }
 
 function showVersion() {
-  console.log('agentic-x402 v0.1.0');
+  console.log('agentic-x402 v0.2.1');
 }
 
 async function main() {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agentic-x402",
-  "version": "0.1.2",
+  "version": "0.2.1",
   "description": "Agent skill for x402 payments - pay for and sell gated content",
   "type": "module",
   "bin": {
@@ -14,6 +14,7 @@
     "SKILL.md"
   ],
   "scripts": {
+    "setup": "tsx scripts/commands/setup.ts",
     "pay": "tsx scripts/commands/pay.ts",
     "fetch": "tsx scripts/commands/fetch-paid.ts",
     "balance": "tsx scripts/commands/balance.ts",

package/scripts/commands/setup.ts

@@ -0,0 +1,296 @@
+#!/usr/bin/env npx tsx
+// x402 Agent Skill - Wallet Setup
+// Creates a new wallet or configures an existing one
+
+import { generatePrivateKey, privateKeyToAccount } from 'viem/accounts';
+import * as fs from 'fs';
+import * as path from 'path';
+import * as readline from 'readline';
+import { homedir } from 'os';
+
+// Global config directory: ~/.x402/
+const CONFIG_DIR = path.join(homedir(), '.x402');
+const CONFIG_PATH = path.join(CONFIG_DIR, '.env');
+
+interface SetupResult {
+  success: boolean;
+  walletAddress?: string;
+  privateKey?: string;
+  isNewWallet?: boolean;
+  error?: string;
+}
+
+function createReadline(): readline.Interface {
+  return readline.createInterface({
+    input: process.stdin,
+    output: process.stdout,
+  });
+}
+
+function prompt(rl: readline.Interface, question: string): Promise<string> {
+  return new Promise((resolve) => {
+    rl.question(question, (answer) => {
+      resolve(answer.trim());
+    });
+  });
+}
+
+function isValidPrivateKey(key: string): boolean {
+  return /^0x[a-fA-F0-9]{64}$/.test(key);
+}
+
+function ensureConfigDir(): void {
+  if (!fs.existsSync(CONFIG_DIR)) {
+    fs.mkdirSync(CONFIG_DIR, { recursive: true, mode: 0o700 });
+  }
+}
+
+function backupExistingConfig(): string | null {
+  if (!fs.existsSync(CONFIG_PATH)) {
+    return null;
+  }
+
+  const timestamp = new Date().toISOString().replace(/[:.]/g, '-');
+  const backupPath = path.join(CONFIG_DIR, `.env.backup.${timestamp}`);
+
+  fs.copyFileSync(CONFIG_PATH, backupPath);
+  fs.chmodSync(backupPath, 0o600);
+
+  return backupPath;
+}
+
+async function main(): Promise<SetupResult> {
+  console.log('x402 Agent Skill - Wallet Setup');
+  console.log('================================\n');
+
+  // Check if config already exists
+  if (fs.existsSync(CONFIG_PATH)) {
+    console.log('Existing config found!');
+    console.log(`Location: ${CONFIG_PATH}\n`);
+
+    // Read existing config and show wallet address
+    const envContent = fs.readFileSync(CONFIG_PATH, 'utf-8');
+    const keyMatch = envContent.match(/EVM_PRIVATE_KEY=0x([a-fA-F0-9]{64})/);
+
+    if (keyMatch) {
+      const existingKey = `0x${keyMatch[1]}` as `0x${string}`;
+      const account = privateKeyToAccount(existingKey);
+
+      console.log('Current Configuration');
+      console.log('---------------------');
+      console.log(`Wallet Address: ${account.address}`);
+      console.log(`Config File:    ${CONFIG_PATH}`);
+
+      const rl = createReadline();
+      console.log('\nOptions:');
+      console.log('  1) Keep existing config (exit)');
+      console.log('  2) Create new wallet (backs up existing config)\n');
+
+      let choice = '';
+      while (choice !== '1' && choice !== '2') {
+        choice = await prompt(rl, 'Enter choice (1 or 2): ');
+        if (choice !== '1' && choice !== '2') {
+          console.log('Please enter 1 or 2');
+        }
+      }
+
+      if (choice === '1') {
+        rl.close();
+        console.log('\nKeeping existing config.');
+        console.log(`\nTo check your balance:`);
+        console.log(`  x402 balance`);
+
+        return {
+          success: true,
+          walletAddress: account.address,
+        };
+      }
+
+      // User wants to reconfigure - backup first
+      rl.close();
+      const backupPath = backupExistingConfig();
+      console.log(`\nExisting config backed up to:`);
+      console.log(`  ${backupPath}`);
+      console.log('');
+
+      // Continue with setup flow below...
+    } else {
+      // Config exists but is invalid - back it up and continue
+      const backupPath = backupExistingConfig();
+      console.log('Invalid config file found (missing private key).');
+      console.log(`Backed up to: ${backupPath}\n`);
+    }
+  }
+
+  const rl = createReadline();
+
+  // Step 1: Wallet choice
+  console.log('Step 1/2: Wallet Setup');
+  console.log('----------------------');
+  console.log('Do you have an existing wallet private key?\n');
+  console.log('  1) Generate a NEW wallet (Recommended for agents)');
+  console.log('  2) Use an EXISTING private key\n');
+
+  let choice = '';
+  while (choice !== '1' && choice !== '2') {
+    choice = await prompt(rl, 'Enter choice (1 or 2): ');
+    if (choice !== '1' && choice !== '2') {
+      console.log('Please enter 1 or 2');
+    }
+  }
+
+  let privateKey: `0x${string}`;
+  let isNewWallet = false;
+
+  if (choice === '1') {
+    // Generate new wallet (recommended)
+    console.log('\nGenerating new wallet...');
+    privateKey = generatePrivateKey();
+    isNewWallet = true;
+    console.log('New wallet created!\n');
+  } else {
+    // User wants to use existing key - show warnings
+    console.log('\n' + '='.repeat(60));
+    console.log('                    SECURITY WARNING');
+    console.log('='.repeat(60));
+    console.log('\nUsing your main wallet with automated agents is RISKY:');
+    console.log('');
+    console.log('  - Agents can sign transactions without your approval');
+    console.log('  - A bug or misconfiguration could drain funds');
+    console.log('  - Private keys stored in env files can be exposed');
+    console.log('');
+    console.log('RECOMMENDED: Use a DEDICATED wallet with limited funds.');
+    console.log('Only transfer what you need for payments to this wallet.');
+    console.log('='.repeat(60) + '\n');
+
+    const confirm = await prompt(rl, 'I understand the risks (type "yes" to continue): ');
+
+    if (confirm.toLowerCase() !== 'yes') {
+      console.log('\nSetup cancelled. Run "x402 setup" again to generate a new wallet.');
+      rl.close();
+      return { success: false, error: 'User cancelled setup' };
+    }
+
+    console.log('\nEnter your private key (0x... format):\n');
+
+    // Loop until we get a valid key
+    let inputKey = '';
+    while (!isValidPrivateKey(inputKey)) {
+      inputKey = await prompt(rl, 'Private key: ');
+
+      if (!isValidPrivateKey(inputKey)) {
+        console.log('Invalid private key format. Must be 0x followed by 64 hex characters.');
+        console.log('Example: 0x1234...abcd (66 characters total)\n');
+      }
+    }
+
+    privateKey = inputKey as `0x${string}`;
+    console.log('\nPrivate key accepted');
+  }
+
+  rl.close();
+
+  // Derive account from private key
+  const account = privateKeyToAccount(privateKey);
+  console.log(`Wallet Address: ${account.address}\n`);
+
+  // Step 2: Create config
+  console.log('Step 2/2: Saving configuration...');
+  ensureConfigDir();
+
+  const envContent = `# x402 Agent Skill Configuration
+# Location: ~/.x402/.env
+# Created: ${new Date().toISOString()}
+#
+# WARNING: Keep this file secret! Never share your private key!
+# This wallet can sign payment transactions automatically.
+
+# Your wallet private key (required)
+EVM_PRIVATE_KEY=${privateKey}
+
+# Network: mainnet or testnet
+# mainnet = Base (chain 8453) - real USDC
+# testnet = Base Sepolia (chain 84532) - test tokens
+X402_NETWORK=mainnet
+
+# Maximum payment limit in USD (safety feature)
+# Payments exceeding this will be rejected
+X402_MAX_PAYMENT_USD=10
+
+# Verbose logging (0 = off, 1 = on)
+X402_VERBOSE=0
+`;
+
+  fs.writeFileSync(CONFIG_PATH, envContent, { mode: 0o600 });
+  console.log(`Config saved to: ${CONFIG_PATH}\n`);
+
+  // Final summary
+  console.log('='.repeat(50));
+  console.log('           SETUP COMPLETE!');
+  console.log('='.repeat(50) + '\n');
+
+  console.log('Your x402 Payment Wallet');
+  console.log('------------------------');
+  console.log(`Address: ${account.address}`);
+  console.log(`Network: Base Mainnet (chain 8453)`);
+  console.log(`Config:  ${CONFIG_PATH}`);
+
+  if (isNewWallet) {
+    console.log('\n' + '!'.repeat(50));
+    console.log('       BACKUP YOUR PRIVATE KEY NOW!');
+    console.log('!'.repeat(50));
+    console.log('\nYour private key (save this securely):');
+    console.log(`\n  ${privateKey}\n`);
+    console.log('Store this in a password manager or secure location.');
+    console.log('If lost, your funds CANNOT be recovered!');
+    console.log('!'.repeat(50));
+  }
+
+  console.log('\nNext Steps');
+  console.log('----------');
+  console.log('1. Fund your wallet with USDC on Base:');
+  console.log(`   Address: ${account.address}`);
+  console.log('');
+  console.log('2. Add a small amount of ETH for gas (optional):');
+  console.log('   ~0.001 ETH is enough for many transactions');
+  console.log('');
+  console.log('3. Check your balance:');
+  console.log('   x402 balance');
+  console.log('');
+  console.log('4. Try paying for an x402 resource:');
+  console.log('   x402 pay https://some-x402-api.com/endpoint');
+
+  console.log('\nBackup Reminder');
+  console.log('---------------');
+  console.log(`Your config is stored at: ${CONFIG_PATH}`);
+  console.log('Back up this file or your private key securely!');
+  console.log('Consider using a password manager like 1Password or Bitwarden.');
+
+  console.log('\nSecurity Tips');
+  console.log('-------------');
+  console.log('- Only fund this wallet with what you need');
+  console.log('- Set X402_MAX_PAYMENT_USD to limit exposure');
+  console.log('- Never share your private key or config file');
+  console.log('- Use testnet first to verify everything works');
+
+  return {
+    success: true,
+    walletAddress: account.address,
+    privateKey: privateKey,
+    isNewWallet,
+  };
+}
+
+// Export for programmatic use
+export { main as setup };
+
+// Run if executed directly
+main().then(result => {
+  if (!result.success) {
+    console.error(`\nSetup failed: ${result.error}`);
+    process.exit(1);
+  }
+}).catch(error => {
+  console.error('Setup error:', error);
+  process.exit(1);
+});