OpenFlow

OpenFlow is a pay-per-use marketplace for AI agent workflows powered by x402 micropayments and Filecoin verifiable storage.

The Problem: Developers constantly rebuild the same AI workflows (transcribe video then translate then summarize, scrape news then analyze, etc). Options are broken: build it yourself (2 weeks + hosting costs), subscribe to SaaS ($99/month for 2 uses), or glue together multiple APIs (integration hell).

The Solution OpenFlow lets developers execute pre-built AI workflows on-demand with one line of code. Install the SDK, run any workflow (video translation, news summarization, data processing), pay micropayments ($0.10-1.00 per execution), and get cryptographically verifiable results stored permanently on Filecoin.

How it works:

1. Workflow creators build AI agents in n8n (visual builder with 400+ integrations)
2. Developers install @openflow/sdk and execute workflows with a single function call
3. x402 protocol handles automatic micropayments (no Stripe, no subscriptions)
4. Each execution state is stored on Filecoin (permanent) and IPFS (fast access)
5. IPNS registry tracks execution status (processing → completed)
6. SDK automatically polls until workflow completes and returns verifiable results

Key Innovation: We solve the "1 IPNS name per account" limitation with a registry pattern - one IPNS name points to a JSON mapping of executionId, then IPFS CID, enabling unlimited concurrent workflow executions with verifiable state transitions.

Tech Stack: x402 payment protocol, Filecoin (Synapse SDK), IPFS/IPNS (Filebase), n8n workflow engine, viem wallet integration, Base Sepolia testnet.

Developer Experience(DX): From install to first result in 2 minutes. No infrastructure, no auth setup, no monthly fees. Just code, crypto, and verifiable outputs.

OpenFlow connects four different technologies to enable pay-per-use AI workflows with verifiable storage. Getting them to work together required solving some unexpected compatibility issues.

x402 Payment Integration: We integrated the x402-fetch library with viem for handling micropayments on Base Sepolia. The x402 protocol works by first sending a request, receiving a 402 Payment Required response, then retrying with a signed payment header. Our Express middleware validates these signatures while keeping the workflow execution asynchronous - the payment validation can't block the actual workflow from running.

Filecoin Storage with Synapse SDK: The first major challenge was discovering that Filecoin piece CIDs (format bafkzci...) are incompatible with IPNS, which requires standard IPFS CIDs (Qm... or bafy...). We implemented a dual-storage approach: upload workflow states to both Filecoin for permanent, verifiable storage, and IPFS for fast retrieval with standard CIDs. Each execution state gets stored twice, which initially seemed redundant but turned out to be necessary. Filecoin also requires files to be at least 127 bytes, so we pad smaller JSON files.

IPNS Registry Pattern: Filebase's free tier only provides one IPNS name, but we need to track unlimited workflow executions. We solved this by creating a registry pattern where the single IPNS name points to a JSON file that maps executionId to IPFS CID. When a workflow completes, we update the registry JSON, upload it to IPFS (getting a new CID), then update the IPNS name to point to this new registry CID. This allows tracking infinite executions with just one IPNS name.

Getting the Filebase integration working took some time - their documentation primarily shows the REST API, but IPNS functionality actually requires using their SDK with S3 credentials through the NameManager class.

n8n Workflow Execution: Each workflow is a permanent webhook in n8n that we call via HTTP. The workflow slug from workflows.json determines which webhook path to hit (e.g., /webhook/video-translator). We initially hardcoded the webhook path but refactored to make it dynamic based on the workflow configuration.

Async Execution Architecture: The execution flow prioritizes fast response times. When a request comes in, we create the initial "processing" state, upload to Filecoin and IPFS, update the IPNS registry, and return the executionId to the client - all within about 300ms. The actual n8n workflow executes in the background without blocking the response.

The SDK polls the /workflow-state/{executionId} endpoint every 2 seconds, resolving the executionId through the IPNS registry to get the current IPFS CID and downloading the state. When the status changes to "completed", the SDK returns the final result.

State Transition Process:

1. Receive request and create "processing" state JSON
2. Upload to Filecoin (get pieceCid) and IPFS (get ipfsCid)
3. Update IPNS registry mapping executionId to ipfsCid
4. Return executionId immediately
5. Execute n8n workflow asynchronously
6. On completion, create "completed" state with output
7. Upload new state to Filecoin and IPFS
8. Update IPNS registry with new ipfsCid
9. SDK detects completion on next poll

Technical Challenges:

• IPNS updates have a propagation delay of 5-10 seconds, which can cause the SDK to briefly see stale state after a workflow completes
• Multiple concurrent workflow completions could create race conditions when updating the shared IPNS registry - we handle this by awaiting the IPNS update operation
• We switched from using workflowId to UUID v4 for execution tracking to support running the same workflow multiple times concurrently

Technology Choices: x402 enables micropayments without traditional payment infrastructure. Filecoin provides cryptographic proof of execution and permanent storage. IPFS gives fast content retrieval, while IPNS provides mutable pointers for tracking state changes. n8n brings 400+ pre-built integrations (OpenAI, Claude, various APIs) so we don't need to build custom connectors for every service.

The complete flow: Express validates x402 payment then initializes workflow state then n8n executes in background then results stored on Filecoin + IPFS then IPNS registry updated then SDK polls until completion. Everything is verifiable without requiring trust in a central server.