---
title: N8N Integration
description: Connect your N8N workflows to X402-enabled APIs
---

# 🔄 N8N Integration

Connect your N8N workflows to X402-enabled APIs with automatic transaction handling.

<Callout type="tip">
  📺 **Watch Video Tutorial**: [Build Your First N8N Workflow](https://www.youtube.com/watch?v=UCC0AGvkc4Q)
</Callout>

---

## OAuth 2.0 Method (Recommended)

The easiest way to connect N8N - no token copying required!

### Step 1: Install N8N Node

```bash
# In your N8N directory
npm install n8n-nodes-agnicwallet

# Or use N8N Community Nodes
# Settings → Community Nodes → Install → "n8n-nodes-agnicwallet"
```

### Step 2: Create OAuth Credential

1. In N8N, go to **Credentials** → **Add Credential**
2. Search for **"AgnicWallet OAuth2 API"**
3. Click **"Connect my account"**
4. Authorize with your wallet and set spending limits
5. You're done! Start using the credential in workflows

### Step 3: Use in Workflow

Add the "AgnicWallet X402 Request" node:

```json
{
  "authentication": "oAuth2",
  "method": "POST",
  "url": "https://api.example.com/x402-endpoint",
  "body": {
    "prompt": "Generate a summary"
  }
}
```

---

## API Key Method

For CI/CD pipelines or programmatic access.

### Step 1: Generate Token

1. Go to [Agnic Dashboard](https://app.agnic.ai)
2. Click **"Connect App"**
3. Set spending limits and label
4. Copy your API token: `agnic_tok_...`

### Step 2: Add to N8N

1. In N8N, add **"AgnicWallet API"** credential
2. Paste your API token
3. Save and use in workflows

---

## MCP Server Method

Connect N8N to the Agnic MCP server for access to all X402 tools.

### Configuration

Add an MCP Client node in your n8n workflow:

```javascript
// 1. Add MCP Client node configuration
{
  "serverType": "HTTP/SSE",
  "serverUrl": "https://mcp.agnic.ai/sse",
  "authHeader": "Authorization: Bearer agnic_tok_sk_live_..."
}

// 2. Use the make_x402_request tool
{
  "tool": "make_x402_request",
  "parameters": {
    "url": "https://api.example.com/data",
    "method": "POST",
    "body": {
      "prompt": "Generate a summary"
    }
  }
}
```

The MCP server handles authorization automatically!

### Available MCP Tools

| Tool | Description | Parameters |
|------|-------------|------------|
| `make_x402_request` | Fetch data from X402 APIs with automatic authorization | `url`, `method`, `headers`, `body` |
| `check_balance` | Check wallet balance | `network` (optional) |
| `get_transaction_history` | View transaction history | `limit`, `startDate`, `network` |
| `discover_apis` | Browse available X402 APIs | `category`, `search`, `maxPrice`, `sort` |
| `fund_wallet` | Get funding instructions | `network` (optional) |

---

## Workflow Examples

### Example 1: Automated Content Generation

This workflow calls an X402-enabled AI API every hour to generate content:

```
[Schedule Trigger: Every 1 hour]
    ↓
[AgnicWallet X402 Request]
  → URL: https://api.example.com/generate
  → Method: POST
  → Body: {"prompt": "Daily news summary"}
    ↓
[Save to Database]
    ↓
[Send Email with Results]
```

### Example 2: Data Enrichment Pipeline

```
[Webhook Trigger]
    ↓
[Get Data from Database]
    ↓
[AgnicWallet X402 Request]
  → URL: https://api.example.com/enrich
  → Method: POST
  → Body: {"data": "{{$json.rawData}}"}
    ↓
[Update Database with Enriched Data]
```

### Example 3: Multi-API Aggregation

```
[Schedule Trigger: Daily]
    ↓
[Split into 3 branches]
    ↓
[X402 API 1: Weather]  [X402 API 2: News]  [X402 API 3: Markets]
    ↓                       ↓                    ↓
[Merge Results]
    ↓
[Generate Report with AI]
    ↓
[Send to Slack]
```

---

## Token Management

### Spending Limits

Protect your workflows with spending limits when generating tokens:

| Limit Type | Description |
|------------|-------------|
| **Per transaction** | Maximum amount per API call |
| **Daily limit** | Total spend allowed per day |
| **Monthly limit** | Total spend allowed per month |

### Multiple Tokens

Create separate tokens for different workflows:

| Token | Use Case | Daily Limit |
|-------|----------|-------------|
| `n8n-content-gen` | Content generation | $20 |
| `n8n-data-enrich` | Data enrichment | $50 |
| `n8n-reporting` | Daily reports | $10 |

---

## Error Handling

### Common Errors

| Status | Error | Solution |
|--------|-------|----------|
| `401` | Invalid token | Check your API token |
| `402` | Insufficient balance | Add USDC to your wallet |
| `429` | Rate limited | Add delay between requests |
| `500` | Provider error | Retry or check API status |

### Error Workflow Pattern

Add error handling to catch transaction failures:

```
[Main Workflow]
    ↓
[Error Trigger] → [Check if 402 Error]
    ↓                    ↓
[Log Error]        [Send "Low Balance" Alert]
```

---

## Best Practices

### 1. Set Appropriate Limits

Match spending limits to your expected usage:

```json
{
  "spending_limits": {
    "per_transaction": 0.50,
    "daily": 10.00,
    "monthly": 100.00
  }
}
```

### 2. Use Descriptive Token Names

Name tokens by their purpose:
- `n8n-prod-content-2025`
- `n8n-staging-test`
- `n8n-analytics-daily`

### 3. Monitor Usage

Check your usage regularly in the [Agnic Dashboard](https://app.agnic.ai/usage).

### 4. Handle Errors Gracefully

Always add error handling nodes to catch transaction failures and insufficient balance errors.

---

## Next Steps

<Cards>
  <Card title="MCP Server" href="/docs/agnicpay-features/mcp-server">
    Connect AI assistants via MCP
  </Card>
  <Card title="API Tokens" href="/docs/authentication/api-tokens">
    Generate and manage API tokens via dashboard
  </Card>
  <Card title="X402 Fetch" href="/docs/x402/x402-fetch">
    Learn about the X402 protocol
  </Card>
</Cards>