agentic-x402 0.1.0

package/README.md

@@ -0,0 +1,223 @@
+# agentic-x402
+
+Agent skill for x402 payments — pay for and sell gated content using USDC on Base.
+
+## What is x402?
+
+[x402](https://docs.x402.org/) is an open payment standard built around HTTP 402 Payment Required. It enables services to charge for API access directly over HTTP using crypto payments.
+
+This skill gives AI agents the ability to:
+- **Pay** for x402-gated resources automatically
+- **Fetch** content with automatic payment handling
+- **Create** payment links to sell content (via 21.cash)
+- **Manage** wallet balances (USDC + ETH for gas)
+
+## Installation
+
+```bash
+npm install -g agentic-x402
+```
+
+Or install locally:
+
+```bash
+pnpm install
+cp config/example.env .env
+# Edit .env and add your EVM_PRIVATE_KEY
+```
+
+## Quick Start
+
+```bash
+# 1. Configure your wallet
+export EVM_PRIVATE_KEY=0x...your_private_key...
+
+# 2. Check balance
+x402 balance
+
+# 3. Pay for a resource
+x402 pay https://api.example.com/paid-endpoint
+
+# 4. Fetch with auto-payment
+x402 fetch https://api.example.com/data --json
+
+# 5. Create a payment link (requires x402-links-server)
+x402 create-link --name "My API" --price 1.00 --url https://api.example.com/premium
+```
+
+## Commands
+
+### balance — Check Wallet Balances
+
+Show your wallet address, USDC balance (for payments), and ETH balance (for gas). Warns if either balance is low.
+
+```bash
+x402 balance
+x402 balance --json
+x402 balance --full
+```
+
+| Flag | Description | Default |
+|------|-------------|---------|
+| `--json` | Output as JSON (address, network, chainId, balances) | — |
+| `--full` | Show full wallet address instead of truncated | — |
+| `-h, --help` | Show help | — |
+
+---
+
+### pay — Pay for an x402-Gated Resource
+
+Make a request to an x402-gated URL. If the server responds with HTTP 402, the CLI extracts payment requirements, verifies the amount is within your max limit, and automatically signs and sends payment. Shows the response body after successful payment.
+
+```bash
+x402 pay https://api.example.com/data
+x402 pay https://api.example.com/submit --method POST --body '{"data":"value"}'
+x402 pay https://api.example.com/data --max 5
+x402 pay https://api.example.com/data --dry-run
+```
+
+| Flag | Description | Default |
+|------|-------------|---------|
+| `<url>` | The URL of the x402-gated resource (positional) | **required** |
+| `--method` | HTTP method | `GET` |
+| `--body` | Request body (for POST/PUT requests) | — |
+| `--header` | Add custom header (can be used multiple times) | — |
+| `--max` | Maximum payment in USD (overrides config) | from config |
+| `--dry-run` | Show payment details without paying | — |
+| `-h, --help` | Show help | — |
+
+If the URL does not require payment (non-402 response), the response is returned directly.
+
+---
+
+### fetch — Fetch with Automatic Payment
+
+A simpler, pipe-friendly version of `pay`. Uses the x402 SDK's wrapped fetch to handle 402 responses automatically. Supports `--json` and `--raw` output modes for easy integration with scripts and agents.
+
+```bash
+x402 fetch https://api.example.com/data
+x402 fetch https://api.example.com/data --json
+x402 fetch https://api.example.com/data --raw
+x402 fetch https://api.example.com/submit --method POST --body '{"key":"value"}'
+```
+
+| Flag | Description | Default |
+|------|-------------|---------|
+| `<url>` | The URL to fetch (positional) | **required** |
+| `--method` | HTTP method | `GET` |
+| `--body` | Request body (for POST/PUT) | — |
+| `--header` | Add header as `"Key: Value"` | — |
+| `--json` | Output as JSON only (for piping to other tools) | — |
+| `--raw` | Output raw response body only (no headers or status) | — |
+| `-h, --help` | Show help | — |
+
+---
+
+### create-link — Create a Payment Link
+
+Create a payment link via the [21.cash](https://21.cash) x402-links-server. You can gate a URL or text content behind a USDC payment. Requires `X402_LINKS_API_URL` and `X402_LINKS_API_KEY` environment variables.
+
+```bash
+x402 create-link --name "Premium Guide" --price 5.00 --url https://mysite.com/guide.pdf
+x402 create-link --name "Secret Message" --price 0.50 --text "The secret is..."
+x402 create-link --name "API Access" --price 1.00 --url https://api.example.com/data --webhook https://mysite.com/webhook
+```
+
+| Flag | Description | Default |
+|------|-------------|---------|
+| `--name` | Name of the payment link | **required** |
+| `--price` | Price in USD (e.g., `"5.00"` or `"0.10"`) | **required** |
+| `--url` | URL to gate behind payment | — |
+| `--text` | Text content to gate behind payment | — |
+| `--desc` | Description of the link | — |
+| `--webhook` | Webhook URL for payment notifications | — |
+| `--json` | Output as JSON | — |
+| `-h, --help` | Show help | — |
+
+> **Note:** Either `--url` or `--text` is required. The link is deployed as a smart contract on Base.
+
+---
+
+### link-info — Get Payment Link Details
+
+Look up details of a payment link by its router address or full URL.
+
+```bash
+x402 link-info 0x1234...5678
+x402 link-info https://21.cash/pay/0x1234...5678
+```
+
+| Flag | Description | Default |
+|------|-------------|---------|
+| `<address>` | Router contract address or full payment URL (positional) | **required** |
+| `--json` | Output as JSON | — |
+| `-h, --help` | Show help | — |
+
+## Configuration
+
+Config is loaded from these locations (in order of priority):
+
+1. Environment variables
+2. `.env` file in current directory
+3. `~/.x402/.env` (global config)
+
+### Environment Variables
+
+#### Required
+
+| Variable | Description |
+|----------|-------------|
+| `EVM_PRIVATE_KEY` | Your wallet private key (0x-prefixed). Used to sign payment authorizations. |
+
+#### Network Settings
+
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `X402_NETWORK` | `mainnet` (Base, chain 8453) or `testnet` (Base Sepolia, chain 84532) | `mainnet` |
+| `X402_MAX_PAYMENT_USD` | Safety limit — payments exceeding this are rejected unless `--max` is used | `10` |
+| `X402_FACILITATOR_URL` | Custom facilitator URL | Coinbase (mainnet) / x402.org (testnet) |
+| `X402_SLIPPAGE_BPS` | Slippage tolerance in basis points (100 bps = 1%) | `50` |
+| `X402_VERBOSE` | Enable verbose logging (`1` = on, `0` = off) | `0` |
+
+#### 21.cash Integration (for link commands)
+
+| Variable | Description |
+|----------|-------------|
+| `X402_LINKS_API_URL` | Base URL of x402-links-server (e.g., `https://21.cash`) |
+| `X402_LINKS_API_KEY` | API key for programmatic link creation |
+
+## Global Options
+
+| Flag | Description |
+|------|-------------|
+| `-h, --help` | Show help for a command |
+| `-v, --version` | Show CLI version |
+
+## CLI Reference
+
+| Category | Command | Description |
+|----------|---------|-------------|
+| **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`) |
+| **Links** | `create-link` | Create a payment link to sell content (21.cash) |
+| **Links** | `link-info <addr>` | Get info about a payment link |
+
+## For Agents
+
+This skill is designed for use with AI agents (Claude Code, OpenClaw, etc.). The `SKILL.md` file contains full agent-readable documentation. Agents can use the `--json` flag on all commands for structured output:
+
+```bash
+# Structured balance output
+x402 balance --json
+
+# Pipe-friendly fetch
+x402 fetch https://api.example.com/data --json
+
+# Raw output for further processing
+x402 fetch https://api.example.com/data --raw
+```
+
+## License
+
+MIT

package/SKILL.md

@@ -0,0 +1,277 @@
+---
+name: agentic-x402
+description: Make x402 payments to access gated APIs and content. Fetch paid resources, check wallet balance, and create payment links. Use when encountering 402 Payment Required responses or when the user wants to pay for web resources with crypto.
+license: MIT
+compatibility: Requires Node.js 20+, network access to x402 facilitators and EVM chains
+metadata:
+  author: monemetrics
+  version: "0.1.0"
+allowed-tools: Bash(x402:*) Bash(npm:*) Read
+---
+
+# x402 Agent Skill
+
+Pay for x402-gated APIs and content using USDC on Base. This skill enables agents to autonomously make crypto payments when accessing paid web resources.
+
+## Quick Reference
+
+| Command | Description |
+|---------|-------------|
+| `x402 balance` | Check USDC and ETH balances |
+| `x402 pay <url>` | Pay for a gated resource |
+| `x402 fetch <url>` | Fetch with auto-payment |
+| `x402 create-link` | Create payment link (seller) |
+| `x402 link-info <addr>` | Get payment link details |
+
+## Setup
+
+1. Install dependencies:
+```bash
+cd {baseDir} && npm install
+```
+
+2. Configure wallet (create `.env` in working directory):
+```bash
+EVM_PRIVATE_KEY=0x...your_private_key...
+X402_NETWORK=mainnet  # or testnet
+```
+
+3. Verify setup:
+```bash
+x402 balance
+```
+
+## Paying for Resources
+
+### When you encounter HTTP 402 Payment Required
+
+Use `x402 pay` to make the payment and access the content:
+
+```bash
+x402 pay https://api.example.com/paid-endpoint
+```
+
+The command will:
+1. Check payment requirements
+2. Verify amount is within limits
+3. Process the payment
+4. Return the gated content
+
+### Automatic payment with fetch
+
+Use `x402 fetch` for seamless payment handling:
+
+```bash
+x402 fetch https://api.example.com/data --json
+```
+
+This wraps fetch with x402 payment handling - if the resource requires payment, it's handled automatically.
+
+### Payment limits
+
+By default, payments are limited to $10 USD. Override with `--max`:
+
+```bash
+x402 pay https://expensive-api.com/data --max 50
+```
+
+Or set globally:
+```bash
+export X402_MAX_PAYMENT_USD=25
+```
+
+### Dry run
+
+Preview payment without executing:
+
+```bash
+x402 pay https://api.example.com/data --dry-run
+```
+
+## Creating Payment Links (Seller)
+
+Create payment links to monetize your own content using x402-links-server:
+
+### Setup for link creation
+
+Add to `.env`:
+```bash
+X402_LINKS_API_URL=https://your-x402-links-server.com
+X402_LINKS_API_KEY=your_api_key
+```
+
+### Create a link
+
+Gate a URL:
+```bash
+x402 create-link --name "Premium API" --price 1.00 --url https://api.example.com/premium
+```
+
+Gate text content:
+```bash
+x402 create-link --name "Secret" --price 0.50 --text "The secret message..."
+```
+
+With webhook notification:
+```bash
+x402 create-link --name "Guide" --price 5.00 --url https://mysite.com/guide --webhook https://mysite.com/payment-hook
+```
+
+### Get link info
+
+```bash
+x402 link-info 0x1234...5678
+x402 link-info https://21.cash/pay/0x1234...5678
+```
+
+## Command Reference
+
+### x402 balance
+
+Check wallet balances.
+
+```bash
+x402 balance [--json] [--full]
+```
+
+Options:
+- `--json`: Output as JSON
+- `--full`: Show full addresses
+
+### x402 pay
+
+Pay for an x402-gated resource.
+
+```bash
+x402 pay <url> [options]
+```
+
+Options:
+- `--method <METHOD>`: HTTP method (default: GET)
+- `--body <JSON>`: Request body for POST/PUT
+- `--max <USD>`: Maximum payment limit
+- `--dry-run`: Preview without paying
+
+### x402 fetch
+
+Fetch with automatic payment.
+
+```bash
+x402 fetch <url> [options]
+```
+
+Options:
+- `--method <METHOD>`: HTTP method (default: GET)
+- `--body <JSON>`: Request body
+- `--json`: Output JSON only (for piping)
+- `--raw`: Output raw response body
+
+### x402 create-link
+
+Create a payment link.
+
+```bash
+x402 create-link --name <name> --price <usd> [options]
+```
+
+Required:
+- `--name <name>`: Link name
+- `--price <usd>`: Price in USD (e.g., "5.00")
+
+Content (one required):
+- `--url <url>`: URL to gate
+- `--text <content>`: Text to gate
+
+Options:
+- `--desc <text>`: Description
+- `--webhook <url>`: Webhook for notifications
+- `--json`: Output as JSON
+
+### x402 link-info
+
+Get payment link details.
+
+```bash
+x402 link-info <router-address> [--json]
+```
+
+## Environment Variables
+
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `EVM_PRIVATE_KEY` | Wallet private key | Required |
+| `X402_NETWORK` | `mainnet` or `testnet` | `mainnet` |
+| `X402_MAX_PAYMENT_USD` | Max payment limit | `10` |
+| `X402_FACILITATOR_URL` | Custom facilitator | Auto |
+| `X402_LINKS_API_URL` | x402-links-server URL | - |
+| `X402_LINKS_API_KEY` | API key for links | - |
+| `X402_VERBOSE` | Enable debug logging | `0` |
+
+## Supported Networks
+
+| Network | Chain ID | CAIP-2 ID |
+|---------|----------|-----------|
+| Base Mainnet | 8453 | eip155:8453 |
+| Base Sepolia | 84532 | eip155:84532 |
+
+## Payment Token
+
+All payments use **USDC** (USD Coin) on the selected network.
+
+- Base Mainnet: `0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913`
+- Base Sepolia: `0x036CbD53842c5426634e7929541eC2318f3dCF7e`
+
+## How x402 Works
+
+1. Client requests a resource
+2. Server responds with `402 Payment Required` + payment details
+3. Client signs a payment authorization (USDC transfer)
+4. Client retries request with payment signature
+5. Server verifies payment via facilitator
+6. Server settles payment on-chain
+7. Server returns the gated content
+
+The x402 protocol is gasless for buyers - the facilitator sponsors gas fees.
+
+## Troubleshooting
+
+### "Missing required environment variable: EVM_PRIVATE_KEY"
+
+Set your wallet private key:
+```bash
+export EVM_PRIVATE_KEY=0x...
+```
+
+Or create a `.env` file in your working directory.
+
+### "Payment exceeds max limit"
+
+Increase the limit:
+```bash
+x402 pay https://... --max 50
+```
+
+### Low balance warnings
+
+Fund your wallet with:
+- **USDC** for payments
+- **ETH** for gas (small amount, ~0.001 ETH)
+
+### Network mismatch
+
+Ensure your wallet has funds on the correct network:
+- `X402_NETWORK=mainnet` → Base mainnet
+- `X402_NETWORK=testnet` → Base Sepolia
+
+## Security Notes
+
+- Never share your private key
+- Start with testnet to verify setup
+- Set reasonable payment limits
+- Review payment amounts before confirming
+
+## Links
+
+- [x402 Protocol Docs](https://docs.x402.org/)
+- [x402 GitHub](https://github.com/coinbase/x402)
+- [Base Network](https://base.org/)

package/bin/cli.ts

@@ -0,0 +1,137 @@
+#!/usr/bin/env npx tsx
+// x402 CLI - Agent skill for x402 payments
+
+import { spawn } from 'child_process';
+import { resolve, dirname } from 'path';
+import { fileURLToPath } from 'url';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const scriptsDir = resolve(__dirname, '../scripts');
+
+interface Command {
+  script: string;
+  description: string;
+  category: 'info' | 'payments' | 'links';
+}
+
+const commands: Record<string, Command> = {
+  // Info commands
+  balance: {
+    script: 'commands/balance.ts',
+    description: 'Check wallet USDC and ETH balances',
+    category: 'info',
+  },
+
+  // Payment commands
+  pay: {
+    script: 'commands/pay.ts',
+    description: 'Pay for an x402-gated resource',
+    category: 'payments',
+  },
+  fetch: {
+    script: 'commands/fetch-paid.ts',
+    description: 'Fetch URL with automatic x402 payment',
+    category: 'payments',
+  },
+
+  // Link commands (21cash integration)
+  'create-link': {
+    script: 'commands/create-link.ts',
+    description: 'Create a payment link to sell content',
+    category: 'links',
+  },
+  'link-info': {
+    script: 'commands/link-info.ts',
+    description: 'Get info about a payment link',
+    category: 'links',
+  },
+};
+
+function showHelp() {
+  console.log(`
+x402 - Agent skill for x402 payments
+
+Usage: x402 <command> [arguments]
+
+Info Commands:
+  balance             Check wallet USDC and ETH balances
+
+Payment Commands:
+  pay <url>           Pay for an x402-gated resource
+  fetch <url>         Fetch URL with automatic x402 payment
+
+Link Commands (21cash integration):
+  create-link         Create a payment link to sell content
+  link-info <addr>    Get info about a payment link
+
+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
+
+For command-specific help: x402 <command> --help
+`);
+}
+
+function showVersion() {
+  console.log('agentic-x402 v0.1.0');
+}
+
+async function main() {
+  const args = process.argv.slice(2);
+
+  if (args.length === 0 || args[0] === '-h' || args[0] === '--help' || args[0] === 'help') {
+    showHelp();
+    process.exit(0);
+  }
+
+  if (args[0] === '-v' || args[0] === '--version' || args[0] === 'version') {
+    showVersion();
+    process.exit(0);
+  }
+
+  const commandName = args[0];
+  const command = commands[commandName];
+
+  if (!command) {
+    console.error(`Unknown command: ${commandName}`);
+    console.error('Run "x402 --help" for available commands.');
+    process.exit(1);
+  }
+
+  const scriptPath = resolve(scriptsDir, command.script);
+  const commandArgs = args.slice(1);
+
+  // Run the script with tsx
+  const child = spawn('npx', ['tsx', scriptPath, ...commandArgs], {
+    stdio: 'inherit',
+    env: {
+      ...process.env,
+      X402_CWD: process.cwd(),
+    },
+  });
+
+  child.on('close', (code) => {
+    process.exit(code ?? 0);
+  });
+
+  child.on('error', (err) => {
+    console.error('Failed to run command:', err.message);
+    process.exit(1);
+  });
+}
+
+main();

package/bin/x402.js

@@ -0,0 +1,57 @@
+#!/usr/bin/env node
+// x402 CLI wrapper - runs the TypeScript CLI via tsx
+
+import { spawn } from 'child_process';
+import { dirname, resolve } from 'path';
+import { fileURLToPath } from 'url';
+import { existsSync } from 'fs';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const cliPath = resolve(__dirname, 'cli.ts');
+
+// Find tsx binary
+function findTsx() {
+  // Check local node_modules first
+  const localTsx = resolve(__dirname, '../node_modules/.bin/tsx');
+  if (existsSync(localTsx)) {
+    return localTsx;
+  }
+
+  // Fall back to npx
+  return null;
+}
+
+const tsxPath = findTsx();
+
+// Suppress experimental warnings
+const env = {
+  ...process.env,
+  NODE_NO_WARNINGS: '1',
+  X402_CWD: process.cwd(),
+};
+
+let child;
+
+if (tsxPath) {
+  // Use local tsx directly
+  child = spawn(tsxPath, [cliPath, ...process.argv.slice(2)], {
+    stdio: 'inherit',
+    env,
+  });
+} else {
+  // Fall back to npx tsx
+  child = spawn('npx', ['tsx', cliPath, ...process.argv.slice(2)], {
+    stdio: 'inherit',
+    env,
+  });
+}
+
+child.on('close', (code) => {
+  process.exit(code ?? 0);
+});
+
+child.on('error', (err) => {
+  console.error('Failed to start x402 CLI:', err.message);
+  console.error('Make sure tsx is installed: npm install -g tsx');
+  process.exit(1);
+});