n8n-nodes-agnic

v1.0.16

Published

6 months ago

n8n community node for AgnicWallet - automated Web3 payments for X402 APIs

n8n-nodes-agnic

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-agnic --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 [email protected], but other community nodes may require [email protected]. 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:latest

USER root
RUN cd /home/node/.n8n/nodes && \
    npm init -y && \
    npm install n8n-nodes-agnic --legacy-peer-deps
USER node

Global Installation (Alternative):

npm install -g n8n-nodes-agnic --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

Go to AgnicWallet
Sign up with email/social login
Your embedded wallet is created automatically

2. Connect to N8N

Option A: OAuth2 (Recommended)

In N8N, add the AgnicWallet X402 Request node
Select OAuth2 authentication
Click Connect my account
Authorize AgnicWallet in the popup
Done! Your wallet is connected

Option B: API Key

Log in to AgnicWallet
Go to Settings → API Tokens
Generate a new token
In N8N, select API Key authentication
Paste your token
Done!

Usage

Basic Example: X402 Protected Content

Simple GET request with automatic payment:

Method: GET
URL: https://www.x402.org/protected

What happens:

Node makes GET request to protected endpoint
Receives 402 Payment Required with payment details
Automatically signs payment ($0.01 USDC) with your AgnicWallet
Retries request with payment proof
Returns protected content with payment metadata

Response:

{
  "data": "<!DOCTYPE html>...<h1>Protected Content</h1><p>Your payment was successful!...</p>",
  "_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:

Body:

{
  "model": "gpt-3.5-turbo",
  "messages": [
    {"role": "user", "content": "{{ $json.userMessage }}"}
  ]
}

This pulls the message from previous nodes in your workflow.

Configuration Options

Authentication

OAuth2 (recommended) - Secure account connection
API Key - For automation and CI/CD

HTTP Methods

GET
POST
PUT
DELETE

Headers

Add multiple custom headers as key-value pairs

Body (POST/PUT only)

JSON body for sending data to the API

How It Works

Make request - Node sends HTTP request to X402 API
Check for 402 - If API returns 402 Payment Required, node extracts payment details
Sign payment - Node calls AgnicWallet backend to sign payment with your wallet
Retry request - Node retries with X-PAYMENT header containing payment proof
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

You create a free account at AgnicWallet
You authorize n8n to use your wallet (OAuth2 or API Key)
When making X402 requests, the node calls api.agnic.ai to sign payments on your behalf
Your wallet is non-custodial (keys managed securely, not stored by AgnicWallet)

Why This Architecture?

No blockchain complexity - You don't manage private keys or gas fees
Automatic payments - Sign once, automate forever
Spending controls - Set monthly limits for safety
Standard pattern - Just like Slack, Notion, and other n8n nodes that use external APIs

Backend API Details

Hosted at: api.agnic.ai (free to use)
Authentication: OAuth2 or API Key
What it does: Signs X402 payments with your authorized wallet
Open source: You can self-host by setting AGNICWALLET_API_URL environment variable

This is the same architecture used by most n8n community nodes that interact with external services.

Payment Details

Network: Base Sepolia (testnet)
Token: USDC
Typical cost: $0.01 per request
Monthly limit: $100 (configurable)
Payment method: EIP-3009 TransferWithAuthorization (gasless)

Security

Non-custodial - Your keys, your crypto
OAuth2 - Industry-standard authentication
Spending limits - Monthly caps prevent overspending
Payment review - See all payments in AgnicWallet dashboard
Revocable access - Disconnect N8N anytime

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:

Fork this node and modify it to use your own payment service
Self-host the AgnicWallet backend (set AGNICWALLET_API_URL 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.agnic.ai goes down?

Your workflows will fail with payment signing errors
Advanced users can self-host the backend for redundancy
Check status at https://pay.agnic.ai

Can n8n approve a node with external dependencies?

Absolutely! Most popular n8n community nodes depend on external APIs:

Slack → api.slack.com
GitHub → api.github.com
Stripe → api.stripe.com
AgnicWallet → api.agnic.ai ✅

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 [email protected] while our AI Agent tools require [email protected] (n8n's built-in version).

Solution: Always install with --legacy-peer-deps:

cd ~/.n8n/nodes
npm install n8n-nodes-agnic --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:

AgnicWallet credentials not connected
Insufficient USDC balance
Backend server down

Solutions:

Reconnect credentials in n8n
Check balance at AgnicWallet
Check backend status

"Request failed after payment"

Causes:

Invalid URL
Wrong headers
Malformed JSON body

Solutions:

Verify URL is correct
Check required headers for the API
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:

✅ Base Sepolia - EVM testnet (free testing with testnet USDC)
✅ Base - EVM mainnet (real USDC payments)
✅ Solana Devnet - SVM testnet (free testing with devnet USDC)
✅ Solana - SVM mainnet (real USDC payments)

The node automatically selects the appropriate network based on your API token configuration and the X402 payment requirements from the API provider.

Limitations

Body types: JSON only (form-encoded coming soon)
Query params: Use in URL for now (dedicated field coming soon)

Contributing

Contributions are welcome! We appreciate bug reports, feature requests, and pull requests.

Bug reports & feature requests: Open an issue
Pull requests: See our Contributing Guide
Questions: Contact us at [email protected]

Support

X402 Standard: x402.org
AgnicWallet: Dashboard

License

MIT License

Roadmap

✅ Completed

Multi-chain support (Base EVM + Solana SVM)
OAuth2 and API Key authentication
Mainnet and testnet support for both chains

v1.1.0 (Next)

Query parameters support
Form-encoded body
Timeout configuration

v1.2.0 (Future)

Additional EVM networks (Polygon, Arbitrum, etc.)
Retry logic with exponential backoff
Enhanced rate limiting

v2.0.0

File upload support
Streaming responses
Webhook triggers

Acknowledgments

Built with:

N8N - Workflow automation
X402 Protocol - HTTP payment standard
Base - L2 blockchain

Made with ❤️ by the AgnicWallet team

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

n8n-nodes-agnic

What is X402?

What is AgnicWallet?

Features

Installation

For self-hosted n8n (Recommended Method):

For Docker:

Global Installation (Alternative):

For n8n.cloud:

Setup

1. Create AgnicWallet Account

2. Connect to N8N

Option A: OAuth2 (Recommended)

Option B: API Key

Usage

Basic Example: X402 Protected Content

Advanced Example: ChatGPT with X402

Example: Dynamic Content

Configuration Options

Authentication

HTTP Methods

Headers

Body (POST/PUT only)

How It Works

Backend Service

How It Works

Why This Architecture?

Backend API Details

Payment Details

Security

FAQ

Is my wallet safe?

Do I need to trust AgnicWallet?

Can I use this node without AgnicWallet?

Is the backend API free?

What if api.agnic.ai goes down?

Can n8n approve a node with external dependencies?

Troubleshooting

"ERESOLVE unable to resolve dependency tree" or "Package subpath './agents' is not defined"

"Payment signing failed"

"Request failed after payment"

"Body field not visible"

Examples & Workflows

API Reference

Node Properties

Supported Networks

Limitations

Contributing

Support

License

Links

Roadmap

✅ Completed

v1.1.0 (Next)

v1.2.0 (Future)

v2.0.0

Acknowledgments