npm package: @itzannetos/x402-tools-claude
Description: Claude Code plugin for x402 payment-gated AI tools on Base network
Author: TzannetosGiannis
Latest version: 2.1.1

# X402 Tools Plugin for Claude Code

Payment-gated AI tools using x402 micropayments on Base network. Access powerful X/Twitter search and OSINT research tools directly from Claude Code via skills.

## Features

### X Search ($0.05 USDC/request)
AI-powered X/Twitter search agent for:
- Real-time trends and breaking news
- Social media sentiment analysis
- Viral content tracking
- Public opinion research

### Find People ($0.15 USDC/request)
Open Source Intelligence (OSINT) agent for:
- Professional background research
- Career timeline verification
- Due diligence on potential hires/partners
- Competitive intelligence on industry leaders
- Investor research on startup founders

### Alpha Finder ($0.03 USDC/request)
Market Oracle for prediction market intelligence:
- Polymarket event research
- Kalshi market analysis
- Searches web, GitHub, Reddit, and X
- Probability assessments and market sentiment
- Arbitrage opportunity identification

## Prerequisites

- [Claude Code](https://docs.anthropic.com/en/docs/claude-code) v1.0.33+
- Ethereum wallet with USDC on Base network
- **NO gas needed** - x402 handles transaction costs

## Installation

### Option 1: Install via Claude Code (Recommended)

Inside Claude Code, run:

```
/plugin marketplace add TzannetosGiannis/x402-tools-claude
/plugin install x402-tools@x402-tools-claude
```

### Option 2: Install from Source

```bash
git clone https://github.com/TzannetosGiannis/x402-tools-claude.git
cd x402-tools-claude
npm install
npm run build
```

Then load the plugin:

```bash
claude --plugin-dir .
```

## Configuration

You need to provide your Ethereum private key to sign payment transactions. The plugin checks for the key in this order:

### Option 1: Configuration File (Recommended)

Create `.claude/x402-tools.json` in your project directory:

```json
{
  "private_key": "your_private_key_here"
}
```

### Option 2: Environment Variable

Set `X402_PRIVATE_KEY` in your `.env` file:

```bash
X402_PRIVATE_KEY=your_private_key_here
```

> **Security Warning**:
> - Never commit your private key to version control
> - Use a dedicated wallet with only the USDC you need for testing
> - The `.claude/x402-tools.json` file is automatically gitignored

## Usage

Once the plugin is installed, Claude will have access to two new skills that it can use automatically:

### X Search
Just ask Claude to search Twitter/X:
```
"What are people saying about AI agents on Twitter?"
```

Claude will use the `x-search` skill automatically.

### Find People
Ask Claude to research someone:
```
"Find information about the founder of Ethereum"
```

Claude will use the `find-people` skill automatically.

## How It Works

```
┌─────────────┐     ┌─────────────┐     ┌─────────────┐     ┌─────────────┐
│ Claude Code │────▶│   Skills    │────▶│ x402-axios  │────▶│ 402box.io   │
│             │     │ (npx CLI)   │     │ (payment)   │     │ (AI agents) │
└─────────────┘     └─────────────┘     └─────────────┘     └─────────────┘
                           │
                           ▼
                    ┌─────────────┐
                    │ Base Chain  │
                    │ (USDC pay)  │
                    └─────────────┘
```

1. You ask Claude to search Twitter or research a person
2. Claude recognizes the task and uses the appropriate skill
3. The skill runs the CLI via npx
4. The x402-axios interceptor automatically signs a USDC payment
5. The 402box.io API processes your request
6. Results are returned to Claude

## CLI Usage (Direct)

You can also use the CLI directly:

```bash
# X/Twitter search
npx @itzannetos/x402-tools-claude x-search "AI trends 2024"

# Find people
npx @itzannetos/x402-tools-claude find-people "Vitalik Buterin"

# Alpha finder (prediction markets)
npx @itzannetos/x402-tools-claude alpha-finder "Bitcoin 100k prediction market odds"
```

## Troubleshooting

### "X402 private key missing"
Make sure you've configured your private key in either `.claude/x402-tools.json` or the `X402_PRIVATE_KEY` environment variable.

### "Not enough USDC in your wallet"
Your wallet needs USDC on the Base network. You can:
1. Bridge USDC from Ethereum mainnet to Base
2. Buy USDC on Base through an exchange
3. Use a faucet for testing (if available)

### Skills not appearing
1. Make sure you're using Claude Code v1.0.33 or later
2. Check that the plugin is installed: `/plugin` → Installed tab
3. Try reinstalling the plugin

## Contributing

Contributions are welcome! Please open an issue or submit a pull request.

## Support

- GitHub Issues: [Report bugs](https://github.com/TzannetosGiannis/x402-tools-claude/issues)
- Email: george@402box.io

## License

MIT License - see [LICENSE](LICENSE) for details.

## Credits

Built on top of the [x402 protocol](https://402box.io) for micropayments on Base network.