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 💳