n8n-nodes-actp

The official n8n community node for the Agent Commerce Transaction Protocol (ACTP) - add AI agent payment rails to any n8n workflow with blockchain-based escrow.

Features

• Simple Mode: User-friendly operations for common payment workflows
• Advanced Mode: Full protocol control for complex integrations
• Adapter Routing: Payments route through ACTP (addresses), x402 (HTTP URLs), or ERC-8004 (agent IDs)
• Mock Runtime: Local development without blockchain connection
• Multi-Network: Support for Base Sepolia (testnet) and Base Mainnet
• Type-safe: Full TypeScript with comprehensive error handling
• Security Built-in: Private key protection, input validation, DoS prevention

Installation

Via n8n UI (Recommended)

1. Go to Settings → Community Nodes
2. Click Install a community node
3. Enter n8n-nodes-actp
4. Click Install

Via npm

npm install n8n-nodes-actp

Via Docker

Add to your n8n Dockerfile:

RUN cd /usr/local/lib/node_modules/n8n && npm install n8n-nodes-actp

Quick Start

1. Create Credentials

1. Go to Credentials → New Credential
2. Search for ACTP API
3. Configure:

Field	Description
Environment	mock (testing), testnet (Base Sepolia), or mainnet (Base)
Private Key	Your wallet private key (required for testnet/mainnet)
RPC URL	Optional custom RPC endpoint

2. Add ACTP Node to Workflow

1. Add a new node and search for ACTP
2. Select your credentials
3. Choose an operation mode (Simple or Advanced)
4. Configure the operation

Operations

Simple Mode

Beginner-friendly operations with smart defaults and helpful action hints.

Operation	Description	Use Case
Send Payment	Create and fund a transaction in one step	Pay an AI agent for a service
Check Status	Get transaction status with next action hints	Monitor payment progress
Start Work	Provider accepts and begins work	Accept a job request
Mark Delivered	Provider marks work as complete	Signal job completion
Release Payment	Release escrowed funds to provider	Approve and pay
Raise Dispute	Dispute a delivery	Contest unsatisfactory work
Cancel	Cancel before delivery	Abort a transaction

Advanced Mode

Full protocol control for complex integrations and custom workflows.

Operation	Description
Create Transaction	Create transaction without funding
Link Escrow	Fund and commit to a transaction
Transition State	Manual state transitions (QUOTED, IN_PROGRESS, DELIVERED)
Release Escrow	Release with optional EAS attestation
Get Transaction	Retrieve full transaction details
Get Escrow Balance	Check locked escrow amount

Transaction Lifecycle

INITIATED → QUOTED → COMMITTED → IN_PROGRESS → DELIVERED → SETTLED
                ↘                      ↘              ↘
              CANCELLED              CANCELLED      DISPUTED → SETTLED

State	Description
INITIATED	Transaction created, awaiting escrow
QUOTED	Provider submitted price quote
COMMITTED	Escrow linked, funds locked
IN_PROGRESS	Provider actively working
DELIVERED	Work delivered with proof
SETTLED	Payment released (terminal)
DISPUTED	Under dispute resolution
CANCELLED	Cancelled before completion

Example Workflows

AI Agent Payment Flow

[Webhook Trigger] → [ACTP: Send Payment] → [AI Agent Node] → [ACTP: Mark Delivered] → [ACTP: Release Payment]

Payment Status Monitor

[Schedule Trigger] → [ACTP: Check Status] → [IF: Is Delivered?] → [Slack: Notify]

Multi-Provider Orchestration

[HTTP Request] → [ACTP: Create Transaction] → [Code: Select Provider] → [ACTP: Link Escrow] → [Wait] → [ACTP: Check Status]

Configuration

Environment Variables

# For testnet operations
BASE_SEPOLIA_RPC=https://sepolia.base.org
BASE_SEPOLIA_PRIVATE_KEY=0x...

# For mainnet operations
BASE_MAINNET_RPC=https://mainnet.base.org
BASE_MAINNET_PRIVATE_KEY=0x...

Credential Fields

Field	Required	Description
environment	Yes	mock, testnet, or mainnet
privateKey	Testnet/Mainnet	Wallet private key (never logged)
rpcUrl	No	Custom RPC endpoint override
stateDirectory	No	Mock mode state persistence path

Error Handling

The node provides structured errors for reliable workflow automation:

ACTPError (base)
├── TransactionNotFoundError
├── InvalidStateTransitionError
├── InsufficientBalanceError
├── DeadlinePassedError
├── ValidationError
│   ├── InvalidAddressError
│   └── InvalidAmountError
└── NetworkError
    └── TransactionRevertedError

Use the Error Trigger node to handle failures gracefully.

Networks

Network	Chain ID	Status
Mock	-	✅ Local Development
Base Sepolia	84532	✅ Testnet
Base Mainnet	8453	✅ Production

Fee Structure

• Platform Fee: 1% of transaction amount
• Minimum Fee: $0.05 USDC
• Gas Fees: Paid by transaction initiator (testnet/mainnet)

Security

• Private Key Protection: Never logged or exposed in errors
• Input Validation: All inputs validated before processing
• DoS Prevention: Query limits and timeout protection
• Zero Address Check: Prevents transactions to burn address
• Timeout/Retry: Configurable blockchain operation timeouts

Development

# Clone repository
git clone https://github.com/agirails/n8n-nodes-actp.git
cd n8n-nodes-actp

# Install dependencies
npm install

# Build
npm run build

# Run tests
npm test

# Run tests with coverage
npm test -- --coverage

# Development mode (watch)
npm run dev

# Lint
npm run lint

# Format
npm run format

Testing with Testnet

# Set environment variables
export BASE_SEPOLIA_RPC=https://sepolia.base.org
export BASE_SEPOLIA_PRIVATE_KEY=0x...

# Run integration tests
npm test

API Reference

Node Properties

Property	Type	Description
mode	simple | advanced	Operation mode
operation	string	Selected operation
provider	string	Provider wallet address
amount	string	Amount in USDC
deadline	string	Transaction deadline
transactionId	string	Existing transaction ID

Output Fields

Field	Type	Description
txId	string	Transaction ID
state	string	Current state
amount	string	Transaction amount
provider	string	Provider address
requester	string	Requester address
escrowId	string	Escrow ID (if linked)
nextAction	string	Suggested next action (Simple mode)

Troubleshooting

"Insufficient balance"

Ensure your wallet has enough USDC for the transaction amount plus gas fees.

"Transaction not found"

Verify the transaction ID is correct and exists on the selected network.

"Invalid state transition"

Check the transaction lifecycle diagram - some transitions are only valid from specific states.

"Private key required"

Testnet and mainnet modes require a private key in credentials.

Requirements

• n8n >= 1.0.0
• Node.js >= 18.10
• Dependencies: @agirails/sdk, ethers

Links

• AGIRAILS Documentation
• GitHub Repository
• TypeScript SDK
• Python SDK
• npm Package
• Discord
• AGIRAILS Website

License

Apache 2.0 License - see LICENSE for details.