n8n-nodes-coinbase-cdp

# n8n-nodes-coinbase-cdp-agentkit

**This is the only open-source n8n node for Coinbase CDP. Never run security-critical crypto tools — wallets, transfers, swaps — from closed-source packages you cannot audit. If you can't read the code, you can lose your funds. [Audit this package yourself.](https://github.com/pvdyck/n8n-nodes-coinbase-cdp)**

n8n community node package for [Coinbase Developer Platform (CDP)](https://docs.cdp.coinbase.com/). Create wallets, transfer tokens, swap assets, and build AI-powered blockchain agents — all from n8n workflows.

> **First AI agent + blockchain integration for any workflow automation platform.**

**3 nodes | 7 resources | 16 operations | 7 AI Agent tools | 12 networks | 100% test coverage**

[![npm](https://img.shields.io/npm/v/n8n-nodes-coinbase-cdp-agentkit)](https://www.npmjs.com/package/n8n-nodes-coinbase-cdp-agentkit)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

---

## Table of Contents

- [Architecture](#architecture)
- [Installation](#installation)
- [Credentials](#credentials)
- [Nodes](#nodes)
  - [Coinbase CDP (Action Node)](#coinbase-cdp-action-node)
  - [Coinbase CDP Tool (AI Agent)](#coinbase-cdp-tool-ai-agent)
  - [Coinbase CDP Trigger](#coinbase-cdp-trigger)
- [Supported Networks](#supported-networks)
- [Example Workflows](#example-workflows)
- [Development](#development)
- [Design Decisions](#design-decisions)
- [Links & References](#links--references)
- [License](#license)

---

## Architecture

This package uses an **AgentKit-first** architecture: 3 focused nodes + 1 shared credential, designed to align with [Coinbase AgentKit](https://docs.cdp.coinbase.com/agent-kit/welcome) conventions while keeping the bundle lightweight by using [`@coinbase/cdp-sdk`](https://github.com/coinbase/cdp-sdk) directly.

```
┌──────────────────────────────────────────────────────────┐
│              n8n-nodes-coinbase-cdp-agentkit              │
│                                                          │
│  ┌─────────────────────────────────────────────────────┐ │
│  │           CoinbaseCdpApi Credential                 │ │
│  │   API Key ID  |  API Secret  |  Wallet Secret (opt) │ │
│  └──────┬──────────────┬──────────────┬────────────────┘ │
│         │              │              │                   │
│         ▼              ▼              ▼                   │
│  ┌────────────┐ ┌────────────┐ ┌──────────────┐         │
│  │ AgentTool  │ │ CoinbaseCdp│ │CoinbaseTrigger│         │
│  │ (AI Tool)  │ │  (Action)  │ │  (Polling)   │         │
│  │ 7 tools    │ │ 7 resources│ │ balance watch│         │
│  └─────┬──────┘ └─────┬──────┘ └──────┬───────┘         │
│        │              │               │                  │
│        └──────┬───────┴───────┬───────┘                  │
│               ▼               ▼                          │
│  ┌──────────────────────────────────────────┐            │
│  │           Shared Layer                    │            │
│  │  cdpClientFactory | networkOptions       │            │
│  │  toolFactory      | types                │            │
│  └────────────────────┬─────────────────────┘            │
└───────────────────────┼──────────────────────────────────┘
                        ▼
              ┌─────────────────┐
              │ @coinbase/cdp-sdk│
              └─────────────────┘
```

> **See [IMPLEMENTATION.md](IMPLEMENTATION.md) for detailed Mermaid architecture diagrams** (rendered on GitHub).

---

## Installation

### n8n Community Nodes (Recommended)

1. Go to **Settings > Community Nodes** in your n8n instance
2. Enter `n8n-nodes-coinbase-cdp-agentkit`
3. Click **Install**

See the [n8n community nodes installation guide](https://docs.n8n.io/integrations/community-nodes/installation/gui-install/) for details.

### Manual Installation

```bash
cd ~/.n8n/custom
npm install n8n-nodes-coinbase-cdp-agentkit
```

Restart n8n after installation. See [manual install docs](https://docs.n8n.io/integrations/community-nodes/installation/manual-install/).

---

## Credentials

You need a **Coinbase CDP API key** from the [CDP Portal](https://portal.cdp.coinbase.com/). See [CDP API Keys documentation](https://docs.cdp.coinbase.com/get-started/docs/cdp-api-keys) for details.

| Field | Required | Description |
|-------|----------|-------------|
| API Key ID | Yes | Your CDP API Key ID (UUID format) |
| API Key Secret | Yes | Your CDP API Key Secret (base64-encoded ES256 private key) |
| Wallet Secret | No | Required for signing transactions (transfers, swaps). Leave empty for read-only operations |

### Getting Your Credentials

1. Go to [portal.cdp.coinbase.com](https://portal.cdp.coinbase.com/)
2. Create a new project (or use an existing one)
3. Navigate to **API Keys** and create a new key
4. Copy the **API Key ID** and **API Key Secret**
5. For transaction signing, also copy the **Wallet Secret** from the key creation screen

> **Note**: The Wallet Secret is only shown once during key creation. If you lose it, you'll need to create a new API key.

---

## Nodes

### Coinbase CDP (Action Node)

The primary node for deterministic blockchain operations. Processes items through a resource/operation pattern. Supports [`usableAsTool: true`](https://docs.n8n.io/integrations/creating-nodes/build/declarative-style-node/#usable-as-tool), so it can also be used directly as an AI Agent tool.

```
Input Items → execute() → Resource Router → CDP SDK → Output Items
                              │
          ┌───────┬───────┬───┴───┬───────┬───────┬────────┐
          ▼       ▼       ▼       ▼       ▼       ▼        ▼
       Account  Solana  Smart  Transfer  Swap   Policy  Balance
```

#### Resources & Operations

**Account** (EVM)

| Operation | Description | Key Parameters |
|-----------|-------------|----------------|
| Get or Create | Get existing or create new EVM account | `accountName` |
| List Balances | List all token balances for an address | `address`, `network` |
| Request Faucet | Request testnet tokens | `address`, `faucetNetwork`, `faucetToken` |

**Solana Account**

| Operation | Description | Key Parameters |
|-----------|-------------|----------------|
| Get or Create | Get or create a Solana account | `accountName` |
| Request Faucet | Request Solana devnet tokens | `address`, `faucetToken` |

**Smart Account**

| Operation | Description | Key Parameters |
|-----------|-------------|----------------|
| Get or Create | Create an ERC-4337 smart account | `ownerAccountName`, `smartAccountName` |

**Transfer**

| Operation | Description | Key Parameters |
|-----------|-------------|----------------|
| Send Native Token | Transfer ETH, MATIC, AVAX, etc. | `accountName`, `to`, `amount`, `network` |
| Send ERC-20 Token | Transfer USDC, DAI, or any ERC-20 | `accountName`, `to`, `amount`, `token`, `network` |

**Swap** (Base & Ethereum only)

| Operation | Description | Key Parameters |
|-----------|-------------|----------------|
| Execute Swap | Swap tokens via DEX | `accountName`, `fromToken`, `toToken`, `fromAmount`, `network` |
| Get Quote | Get swap quote without executing | `accountName`, `fromToken`, `toToken`, `fromAmount`, `network` |

**Policy** (see [CDP Policy docs](https://docs.cdp.coinbase.com/cdp-apis/docs/welcome))

| Operation | Description | Key Parameters |
|-----------|-------------|----------------|
| List | List all policies | — |
| Get | Get a policy by ID | `policyId` |
| Create | Create a new policy | `policyJson` |
| Update | Update a policy | `policyId`, `policyJson` |
| Delete | Delete a policy | `policyId` |

**Balance**

| Operation | Description | Key Parameters |
|-----------|-------------|----------------|
| List Token Balances | List all token balances for an address | `address`, `network` |

---

### Coinbase CDP Tool (AI Agent)

Connect blockchain operations to n8n's AI Agent node. Each tool is a [LangChain `DynamicStructuredTool`](https://v03.api.js.langchain.com/classes/_l

[truncated…]