x402-tools

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 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

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

Then load the plugin:

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:

{
  "private_key": "your_private_key_here"
}

Option 2: Environment Variable

Set X402_PRIVATE_KEY in your .env file:

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:

# 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
• Email: george@402box.io

License

MIT License - see LICENSE for details.

Credits

Built on top of the x402 protocol for micropayments on Base network.