x402 Pocket Nodes for n8n

Seamlessly integrate x402 payment protocol with your n8n workflows. Make HTTP requests to x402-enabled APIs with automatic Solana/USDC payment handling.

🎯 What is x402?

x402 is an HTTP payment protocol that allows APIs to request micropayments for access. Think "HTTP 402 Payment Required" - but actually implemented with Solana blockchain payments.

📦 Installation

Option 1: n8n Community Nodes (Recommended)

1. Open n8n
2. Go to Settings → Community Nodes
3. Click Install a community node
4. Enter: @blockchain-hq/n8n-nodes-x402-pocket
5. Click Install

Option 2: Manual Installation

cd ~/.n8n/nodes
npm install @blockchain-hq/n8n-nodes-x402-pocket

Then restart n8n.

🚀 Quick Start

1. Setup Your Wallet (One-Time)

[Manual Trigger] → [x402 Wallet Manager]

1. Add x402 Wallet Manager node
2. Select Devnet (for testing)
3. Run the workflow
4. Copy the wallet address from output
5. Fund it at https://spl-token-faucet.com/
6. Re-run to verify funding

2. Make x402 Requests

[Trigger] → [x402 Wallet Manager] → [x402 Client] → [Process Data]

1. Add x402 Wallet Manager and x402 Client nodes
2. Connect them with a line
3. Configure the Client with your API endpoint
4. Run! Payments happen automatically

📖 Full Setup Guide

🧩 Included Nodes

x402 Wallet Manager

Generate and manage a persistent Solana wallet for x402 payments.

Features:

• ✅ Generate wallet once, use everywhere
• ✅ Check balances (USDC & SOL)
• ✅ Get funding instructions
• ✅ Reset wallet if needed

Use Cases:

• Initial wallet setup
• Balance monitoring
• Wallet management

x402 Client

Make HTTP requests to x402-enabled APIs with automatic payment.

Features:

• ✅ Automatic x402 payment handling
• ✅ Support for GET, POST, PUT, DELETE
• ✅ Custom headers and request bodies
• ✅ Configurable payment limits
• ✅ Transaction details in output
• ✅ Works with Wallet Manager or auto-generate mode

Use Cases:

• Access paid AI APIs
• Fetch paid data feeds
• Call micropayment APIs
• Monetize your own services

x402 Mock Server

Test x402 integration without real blockchain transactions.

Features:

• ✅ Simulates x402 payment flow
• ✅ No real money needed
• ✅ Perfect for development

📋 Examples

Simple Data Fetch

[Schedule: Every hour]
    ↓
[x402 Wallet Manager]
    ↓
[x402 Client]
  URL: https://api.weather-x402.com/forecast
  Method: POST
  Body: {"city": "San Francisco"}
    ↓
[Save to Database]

AI Text Generation

[Webhook Trigger]
    ↓
[x402 Wallet Manager]
    ↓
[x402 Client]
  URL: https://ai-api.example.com/generate
  Method: POST
  Body: {"prompt": "{{$json.query}}"}
    ↓
[Send Response]

Conditional Payments

[Manual Trigger]
    ↓
[x402 Wallet Manager]
    ↓
[IF: Balance > 5 USDC?]
    ↓ true
[x402 Client]
  URL: https://premium-api.com/data
    ↓
[Process Results]

🔧 Configuration

Wallet Manager Settings

| Setting | Description | Values | | ------- | ------------------ | ------------------------------------- | | Network | Blockchain network | Devnet, Mainnet | | Action | What to do | Get Info, Check Balance, Reset Wallet |

Client Settings

| Setting | Description | Default | | ------------- | ----------------------------- | ---------------------------- | | Wallet Source | Where to get wallet | Wallet Manager (recommended) | | Resource URL | x402 API endpoint | - | | HTTP Method | Request method | POST | | Request Body | JSON payload | {} | | Auto-Pay | Automatically pay if required | true | | Max Payment | Safety limit (USDC) | 1 | | Headers | Custom HTTP headers | - |

🔒 Security

• 🔐 Wallets are stored in n8n's encrypted database
• 🔐 Private keys never leave your n8n instance
• 🔐 Use Devnet for testing (no real money)
• 🔐 Set payment limits to avoid overspending
• 🔐 Monitor balances regularly

🌐 Networks

Devnet (Testing)

• Free test tokens
• No real value
• USDC Faucet: https://spl-token-faucet.com/
• SOL Faucet: https://faucet.solana.com/

Mainnet (Production)

• Real money
• Buy USDC on exchanges
• Need SOL for transaction fees

🛠️ Development

Build from Source

# Clone the repo
git clone https://github.com/blockchain-hq/x402-pocket-nodes
cd x402-pocket-nodes

# Install dependencies
pnpm install

# Build
pnpm run build

# Link to n8n (for development)
npm link
cd ~/.n8n/nodes
npm link @blockchain-hq/n8n-nodes-x402-pocket

Project Structure

src/
├── nodes/
│   ├── X402Client/           # Client node
│   ├── X402MockServer/       # Mock server node
│   └── X402WalletManager/    # Wallet manager node
├── utils/
│   ├── solana.utils.ts       # Solana helpers
│   ├── x402.client.ts        # x402 client logic
│   ├── x402.server.ts        # x402 server logic
│   └── x402.types.ts         # Type definitions
└── index.ts                  # Entry point

📝 TODO / Roadmap

• [ ] Add support for more payment schemes (hashlock, invoice)
• [ ] Support for other tokens (SOL, custom SPL tokens)
• [ ] Wallet credential type for better security
• [ ] Multi-wallet support
• [ ] Payment history tracking
• [ ] Balance alerts/notifications
• [ ] Support for other blockchains (Ethereum, etc.)

🤝 Contributing

Contributions are welcome! Please:

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Write tests if applicable
5. Submit a pull request

📄 License

MIT License - see LICENSE file

🔗 Links

• x402 Protocol Spec
• n8n Documentation
• Solana Documentation
• Report Issues

💬 Support

• 📖 Check WALLET_SETUP.md for detailed setup guide
• 🐛 Report bugs via GitHub Issues
• 💡 Feature requests welcome!

🎉 Credits

Built with ❤️ for the n8n and Solana communities.

Made with n8n 🚀 Powered by Solana ⚡ Following x402 Protocol 💳