Description
n8n-nodes-agnicwallet
N8N community node for AgnicWallet – automated Web3 payments for X402-enabled APIs.
> ⭐ If you find this node useful, please star the repository on GitHub!
Make HTTP requests to X402-enabled APIs with automatic blockchain payment handling via AgnicWallet. No manual wallet management, no complex crypto operations – just authenticate and automate.
What is X402?
X402 is an open standard for HTTP-based payments. APIs return a 402 Payment Required status with payment details, and your wallet automatically handles the payment to unlock the resource.
What is AgnicWallet?
AgnicWallet is a non-custodial Web3 wallet service that handles blockchain payments automatically. Connect once, then all X402 payments happen seamlessly in the background.
Features
- ✅ Automatic X402 payment handling – No manual wallet interactions
- ✅ OAuth2 authentication – Secure connection to your AgnicWallet
- ✅ API Key support – For programmatic access and CI/CD
- ✅ Multiple HTTP methods – GET, POST, PUT, DELETE
- ✅ Custom headers – Add any headers your API needs
- ✅ JSON body support – For POST/PUT requests
- ✅ Payment metadata – See exactly what you paid and when
- ✅ Monthly spending limits – Built-in safety controls
- ✅ Multi-chain support – Base (EVM) and Solana networks, both testnet and mainnet
Installation
For self-hosted n8n (Recommended Method):
Install in the n8n custom nodes directory:
cd ~/.n8n/nodes
npm init -y # Only needed first time
npm install n8n-nodes-agnicwallet --legacy-peer-deps
Then restart n8n:
n8n start
> Why --legacy-peer-deps?
>
> This flag prevents npm from installing conflicting versions of langchain. Our node uses n8n’s built-in langchain@0.3.x, but other community nodes may require langchain@1.x. Without this flag, npm may fail with dependency conflicts or install an incompatible version.
>
> You can also set this globally:
>
> echo "legacy-peer-deps=true" >> ~/.npmrc
> For Docker:
Add to your Dockerfile:
FROM n8nio/n8n:latestUSER root
RUN cd /home/node/.n8n/nodes &&
npm init -y &&
npm install n8n-nodes-agnicwallet --legacy-peer-deps
USER node
Global Installation (Alternative):
npm install -g n8n-nodes-agnicwallet --legacy-peer-deps
For n8n.cloud:
Not yet available. This node must first be approved as a community node by the n8n team.
Setup
1. Create AgnicWallet Account
1. Go to AgnicWallet
2. Sign up with email/social login
3. Your embedded wallet is created automatically
2. Connect to N8N
#### Option A: OAuth2 (Recommended)
1. In N8N, add the AgnicWallet X402 Request node
2. Select OAuth2 authentication
3. Click Connect my account
4. Authorize AgnicWallet in the popup
5. Done! Your wallet is connected
#### Option B: API Key
1. Log in to AgnicWallet
2. Go to Settings → API Tokens
3. Generate a new token
4. In N8N, select API Key authentication
5. Paste your token
6. Done!
Usage
Basic Example: X402 Protected Content
Simple GET request with automatic payment:
GEThttps://www.x402.org/protectedWhat happens:
1. Node makes GET request to protected endpoint
2. Receives 402 Payment Required with payment details
3. Automatically signs payment ($0.01 USDC) with your AgnicWallet
4. Retries request with payment proof
5. Returns protected content with payment metadata
Response:
{
"data": "...Protected Content
Your payment was successful!...
",
"_agnicWallet": {
"paymentMade": true,
"amountPaid": 0.01,
"timestamp": "2025-10-28T13:46:44.079Z"
}
}
Advanced Example: ChatGPT with X402
For POST requests with JSON body, see the advanced integration example in the documentation.
Example: Dynamic Content
Use N8N expressions for dynamic requests:
{
"model": "gpt-3.5-turbo",
"messages": [
{"role": "user", "content": "{{ $json.userMessage }}"}
]
}
This pulls the message from previous nodes in your workflow.
Configuration Options
Authentication
HTTP Methods
Headers
Add multiple custom headers as key-value pairs
Body (POST/PUT only)
JSON body for sending data to the API
How It Works
1. Make request – Node sends HTTP request to X402 API
2. Check for 402 – If API returns 402 Payment Required, node extracts payment details
3. Sign payment – Node calls AgnicWallet backend to sign payment with your wallet
4. Retry request – Node retries with X-PAYMENT header containing payment proof
5. Return response – API validates payment and returns protected resource
Backend Service
This node requires the AgnicWallet backend API to function. This is by design and secure.
How It Works
1. You create a free account at AgnicWallet
2. You authorize n8n to use your wallet (OAuth2 or API Key)
3. When making X402 requests, the node calls api.agnicpay.xyz to sign payments on your behalf
4. Your wallet is non-custodial (keys managed securely, not stored by AgnicWallet)
Why This Architecture?
Backend API Details
api.agnicpay.xyz (free to use)AGNICWALLETAPIURL environment variableThis is the same architecture used by most n8n community nodes that interact with external services.
Payment Details
Security
FAQ
Is my wallet safe?
Yes! AgnicWallet is non-custodial. Your private keys are managed securely using industry-standard key management infrastructure, never stored on AgnicWallet servers. The backend only signs transactions you’ve authorized.
Do I need to trust AgnicWallet?
Yes, but only as much as you trust Slack, Notion, or Google when using their n8n nodes. You’re authorizing AgnicWallet to sign X402 payments on your behalf within your spending limits.
Can I use this node without AgnicWallet?
No. This node is specifically designed to work with AgnicWallet’s backend API. However, you can:
AGNICWALLETAPIURL environment variable)Is the backend API free?
Yes! The AgnicWallet service is free to use. You only pay blockchain transaction costs (USDC payments).
What if api.agnicpay.xyz goes down?
Can n8n approve a node with external dependencies?
Absolutely! Most popular n8n community nodes depend on external APIs:
This is standard practice and well-documented in the node’s README.
Troubleshooting
“ERESOLVE unable to resolve dependency tree” or “Package subpath ‘./agents’ is not defined”
Cause:
Conflicting langchain versions between community nodes. Some nodes require langchain@1.x while our AI Agent tools require langchain@0.3.x (n8n’s built-in version).
Solution:
Always install with --legacy-peer-deps:
cd ~/.n8n/nodes
npm install n8n-nodes-agnicwallet --legacy-peer-deps
Or set it globally:
echo "legacy-peer-deps=true" >> ~/.npmrc
If you already installed without this flag, clean up and reinstall:
cd ~/.n8n/nodes
rm -rf node_modules package-lock.json
npm install --legacy-peer-deps
“Payment signing failed”
Causes:
Solutions:
1. Reconnect credentials in n8n
2. Check balance at AgnicWallet
3. Check backend status
“Request failed after payment”
Causes:
Solutions:
1. Verify URL is correct
2. Check required headers for the API
3. Validate JSON syntax
“Body field not visible”
The body field only appears when Method is POST or PUT. For GET requests, no body is shown (HTTP standard).
Examples & Workflows
For example workflows and advanced use cases, check the documentation included with this package.
API Reference
Node Properties
| Property | Type | Required | Description |
|———-|——|———-|————-|
| authentication | options | Yes | OAuth2 or API Key |
| method | options | Yes | HTTP method |
| url | string | Yes | X402 API endpoint |
| headers | collection | No | Custom headers |
| body | json | No | JSON body (POST/PUT only) |
Supported Networks
AgnicWallet supports multiple blockchain networks for X402 payments:
The node automatically selects the appropriate network based on your API token configuration and the X402 payment requirements from the API provider.
Limitations
Contributing
Contributions are welcome! We appreciate bug reports, feature requests, and pull requests.
Support
License
MIT License
Links
Roadmap
✅ Completed
v1.1.0 (Next)
v1.2.0 (Future)
v2.0.0
Acknowledgments
Built with:
—
Made with ❤️ by the AgnicWallet team
