The official Masumi n8n community node provides Cardano blockchain paywall functionality for monetizing n8n workflows on Masumi Network.
Installation Prerequisites
Deploy Masumi Payment Service
You need a running Masumi payment service instance. Get one up and running in less than 5 minutes by deploying on Railway:
Top Up Your Wallets
You need ADA on your selling wallet for registering an agent, and ADA on your buying wallet to test the full flow. Get test-Ada on:
Register an Agent
Register an agent on Masumi registry using your main n8n workflow URL. Read more . By registering your agent you provide:
Price of the execution
Description
Example outputs
Prepare Your Credentials
You will need to provide:
Masumi Payment service admin key Agent identifier vkey - selling wallet verification key You can get all these keys from the dashboard on your running Masumi Payment service. Configuration
Add Credential
In n8n, go to Credentials → Add Credential
Search for Masumi
Search for “Masumi Paywall API” in the dropdown
Configure Fields
Field Description Payment Service URL Base URL of your Masumi service API Key Your Masumi service API key Agent Identifier Your registered agent ID Seller Verification Key Cardano wallet verification key Network Preprod (testnet) or Mainnet
3-Node System Architecture This package provides three specialized nodes for building complete payment-gated workflows.
Node Types
Masumi Paywall Trigger Webhook receiver for external requests
Masumi Paywall Respond Responds to webhooks, creates/updates jobs
Masumi Paywall Handles payment polling and workflow execution
Each node type provides a user-friendly mostly dropdown-driven operation mode selection or output templates. There is also a reference implementation workflow json available on the repo. Consider using it as starter point.
Job Storage System Jobs are stored in n8n static data (this.getWorkflowStaticData('global')) which persists across executions and survives n8n restarts.
interface Job { job_id : string ; // Unique 14-character hex identifier identifier_from_purchaser : string ; // Hex-encoded user identifier input_data : Record < string , any >; // Parsed input parameters status : 'pending' | 'awaiting_payment' | 'awaiting_input' | 'running' | 'completed' | 'failed' ; payment ?: { // Payment details (when created) blockchainIdentifier : string ; inputHash : string ; payByTime : string ; // String timestamp submitResultTime : string ; // String timestamp unlockTime : string ; // String timestamp externalDisputeUnlockTime : string ; // String timestamp }; result ?: any ; // Business logic output error ?: string ; // Error message if failed created_at : string ; // ISO timestamp updated_at : string ; // ISO timestamp }
Required Workflow Architecture You need to create 5 separate endpoints with mini-workflows for complete MIP-003 compliance. The endpoints should provide MIP-003 compliant responses, hence you must connect triggers to the respond nodes. The triggers and response nodes are separated to give you flexibility.
You don’t need to specify most of the endpoint and respond pairs - you set them up by just selecting the operation mode for each node from a dropdown. The 3-nodes-architecture is basically Lego™ and if you read the descriptions you are going to connect everything correctly by just following common sense and MIP-003.
Split Workflow Architecture : Starting from v0.5.0, jobs are immediately accessible after creation via a split workflow design that separates job creation from payment polling for better responsiveness.1. /availability Endpoint Purpose : Health check to confirm agent is online (you can manually select unavailable from a dropdown){ "status" : "success" , "availability" : "available" }
Purpose : Return input schema for the agent - this one you need to specify manually according to your business logic and agentic workflow functionality{ "status" : "success" , "input_schema" : { "prompt" : { "type" : "string" , "description" : "Text to process" } } }
3. /start_job Endpoint Purpose : Create payment request and job, return payment details immediately; automatically triggers internal payment polling in background{ "identifier_from_purchaser" : "user123" , "input_data" : [ { "key" : "prompt" , "value" : "analyze this text" } ] }
4. /status Endpoint Purpose : Return current job status and results (in case the job was fulfilled) Awaiting Payment
Running
Completed
Status is immediately accessible after starting the job: { "job_id" : "a1b2c3d4e5f678" , "status" : "awaiting_payment" , "paybytime" : 1756143592 , "message" : "Waiting for payment confirmation on blockchain" }
Status is set after payment is confirmed: { "job_id" : "a1b2c3d4e5f678" , "status" : "running" }
Status is set after the business logic has been fulfilled: { "job_id" : "a1b2c3d4e5f678" , "status" : "completed" , "paybytime" : 1756143592 , "result" : { "text" : "Business logic output here..." }, "message" : "Job completed successfully" }
5. /start_polling Endpoint (Internal) Purpose : Internal webhook triggered automatically after job creation to handle payment polling separatelyInput (Automatically sent)
{ "job_id" : "a1b2c3d4e5f678" }
This endpoint enables the split workflow architecture where:
Immediate Job Creation
Job creation completes immediately (jobs become accessible)
Background Polling
Payment polling runs as a separate background process
Non-Blocking Flow
No blocking operations in the job creation flow
Business Logic Add your actual business logic by wrapping it with Masumi Paywall on the input and Masumi Paywall Respond on the output:
In the reference template, the Basic LLM Chain is playing a role of a “business logic”. Consider replacing this block with your full business logic or a shortcut to a separate n8n workflow.
Workflow Execution Flow The complete flow for the Split Workflow Architecture (v0.5.0+):
Job Created
/start_job endpoint creates payment request and job, returns immediately with fire-and-forget webhook triggering
Job Accessible
Job status is immediately available via /status endpoint (no longer blocked)
Internal Polling
MasumiPaywallRespond automatically triggers /start_polling internal webhook
Payment Polling
Separate workflow polls Masumi Payment service for payment confirmation
Status Update
Job status changes awaiting_payment → running when payment detected
Payment Confirmed
Once FundsLocked is detected, business logic workflow starts
Business Logic Execution
Your actual processing (LLM, API calls, data transformation) happens
Result Storage
MasumiPaywallRespond saves result and updates status to completed
Getting Results
Consumer can get results by checking status with job_id
Key Improvement : Jobs are no longer “not found” immediately after creation - they’re accessible with awaiting_payment status right away.
Integration with External Systems Sokosumi Marketplace
Direct API
User Initiates
User clicks “hire” in Sokosumi after filling out the form (your input_data)
Job Creation
Sokosumi calls your /start_job → Creates payment request → Job immediately accessible
Background Polling
Internal webhook automatically starts payment polling in background
Payment Handling
Sokosumi handles blockchain payment using returned payment data
Execution
Background polling detects FundsLocked → Starts business logic workflow
Results
Sokosumi polls /status → Gets results when completed
Start Job
External system calls /start_job → Gets payment details → Job immediately accessible
Auto Polling
Background payment polling automatically starts
Manual Payment
External system or user manually sends funds to blockchain
Processing
Background polling detects payment → Processes job → Returns results via /status
Error Behavior MasumiPaywall node throws NodeOperationError when payment fails or times out, causing the workflow to show as failed (red) in n8n and preventing execution of subsequent nodes until payment is confirmed. This behavior occurs unless “Continue on Fail” is enabled in node settings.
Payment States Payment confirmed, workflow continues
Payment pending, most likely you are still polling via MasumiPaywall node
The following states will cause workflow failure:
FundsOrDatumInvalidRefundRequestedDisputedRefundWithdrawnDisputedWithdrawn Development Build and Lint
Test Payment Status
npm install && npm run build && npm run lint
You probably want to clean the npm nodes cache on n8n and restart your n8n instance if you are updating this package. Also consider incrementing versions, even temporary, so that you see which version you are testing on n8n.
License MIT License 
