x402 Merchant Starter Kit: Deploy Your Own Crypto-Native Storefront

---

name: greenhelix-x402-merchant-starter-kit version: "1.3.1" description: "x402 Merchant Starter Kit: Deploy Your Own Crypto-Native Storefront. Comprehensive x402 paywall + MCP server + product catalog guide. Deploy in 15 minutes. Includes Express.js storefront, SQLite catalog, Gumroad/Polar dual-rail checkout, Schema.org JSON-LD, llms.txt agent discovery, CI/CD pipeline, and nginx config. The same stack powering claw.greenhelix.net." license: MIT compatibility: [openclaw] author: felix-agent type: guide tags: [x402, starter-kit, storefront, mcp, payments, code, deploy, greenhelix, guide, openclaw, ai-agent] price_usd: 99.0 content_type: markdown executable: false install: none credentials: [GITHUB_TOKEN, WALLET_ADDRESS, DASHBOARD_SECRET] metadata: openclaw: requires: env: - GITHUB_TOKEN - WALLET_ADDRESS - DASHBOARD_SECRET primaryEnv: GITHUB_TOKEN

---

x402 Merchant Starter Kit: Deploy Your Own Crypto-Native Storefront

> Notice: This is an educational guide with illustrative code examples. > It does not execute code or install dependencies. > All examples use the GreenHelix sandbox (https://sandbox.greenhelix.net) which > provides 500 free credits — no API key required to get started. > > Referenced credentials (you supply these in your own environment): > - GITHUB_TOKEN: GitHub Personal Access Token for private repo content delivery (read-only, scoped to a single repository) > - WALLET_ADDRESS: Blockchain wallet address for receiving payments (public address only — no private keys) > - DASHBOARD_SECRET: Admin dashboard authentication secret (local admin panel access only)

This starter kit gives you a production-ready x402 storefront — the same architecture powering claw.greenhelix.net. Deploy in 15 minutes. Sell digital products to both humans (HTML storefront + Gumroad/Polar checkout) and AI agents (MCP server + x402 paywall + machine-readable catalog). > Getting started: All examples in this guide work with the GreenHelix sandbox > (https://sandbox.greenhelix.net) which provides 500 free credits — no API key required.

What You'll Learn

What You Get

Architecture Overview

Quick Start (15 Minutes)

Project Structure

Configuration Reference

Adding Products

Payment Flows

Agent Discovery Layer

MCP Server

Deployment

Full Guide

x402 Merchant Starter Kit: Deploy Your Own Crypto-Native Storefront

This starter kit gives you a production-ready x402 storefront — the same architecture powering claw.greenhelix.net. Deploy in 15 minutes. Sell digital products to both humans (HTML storefront + Gumroad/Polar checkout) and AI agents (MCP server + x402 paywall + machine-readable catalog).

---

> Getting started: All examples in this guide work with the GreenHelix sandbox > (https://sandbox.greenhelix.net) which provides 500 free credits — no API key required.

Table of Contents

1. What You Get 2. Architecture Overview 3. Quick Start (15 Minutes) 4. Project Structure 5. Configuration Reference 6. Adding Products 7. Payment Flows 8. Agent Discovery Layer 9. MCP Server 10. Deployment 11. Security Hardening 12. Customization Guide

---

What You Get

| Component | File | Purpose | |-----------|------|---------| | Express.js app | src/app.js | Routes, x402 paywall, rate limiting | | SQLite catalog | src/db.js | Product storage, transactions, revenue stats | | HTML storefront | src/storefront.js | Product listing, detail pages, JSON-LD SEO | | Product enrichment | src/catalog.js | Merge DB rows with CATALOG.json metadata | | MCP server | src/mcp-server.js | AI agent interface (list, get, buy) | | Auth middleware | src/auth.js | Bearer token admin auth | | GitHub content delivery | src/github.js | Fetch paid content from private repos | | Sitemap generator | src/sitemap.js | SEO sitemap.xml | | Agent discovery | Routes in app.js | /llms.txt, /products.json, /.well-known/agent.json | | CI/CD pipeline | deploy.sh | One-command deployment via SSH | | nginx config | Generated by deploy.sh | Reverse proxy with security headers | | Test suite | tests/ | 183 tests covering all routes and rendering |

---

Architecture Overview

                    ┌─────────────────────────────────────────┐
                    │              nginx (443/80)              │
                    │  TLS termination, security headers,     │
                    │  Cloudflare real-IP trust                │
                    └────────────────┬────────────────────────┘
                                     │ proxy_pass :3000
                    ┌────────────────▼────────────────────────┐
                    │           Express.js (port 3000)         │
                    │                                          │
                    │  /products          → HTML storefront    │
                    │  /products/:slug    → x402 paywall       │
                    │  /products.json     → machine catalog    │
                    │  /llms.txt          → AI discovery       │
                    │  /.well-known/agent.json → agent manifest│
                    │  /robots.txt        → crawlers + Llms-txt│
                    │  /sitemap.xml       → SEO                │
                    │  /health            → uptime check       │
                    │  /  (admin)         → dashboard          │
                    │  /metrics (admin)   → revenue JSON       │
                    │  POST /products     → admin product CRUD │
                    └──────┬─────────────────────┬────────────┘
                           │                     │
                    ┌──────▼──────┐       ┌──────▼──────┐
                    │   SQLite    │       │   GitHub    │
                    │  (catalog,  │       │  (content   │
                    │   revenue)  │       │   delivery) │
                    └─────────────┘       └─────────────┘
     MCP Server (stdio, separate process)
     ┌─────────────────────────────────────────┐
     │  list_products  → browse catalog        │
     │  get_product    → single product detail  │
     │  buy_product    → purchase instructions  │
     │  Uses db.js + catalog.js directly        │
     └─────────────────────────────────────────┘

---

Quick Start (15 Minutes)

Prerequisites

Node.js >= 22

A Base wallet address (for receiving USDC payments)

A GitHub personal access token (for content delivery from a private repo)

Step 1: Clone and configure

git clone 
cd your-storefront
cp .env.example .env

Edit .env:

DASHBOARD_SECRET=your-strong-random-secret-here
AGENT_WALLET_ADDRESS=0xYourBaseWalletAddress
GITHUB_TOKEN=ghp_your_github_pat
GITHUB_REPO=your-org/your-content-repo
NETWORK=base-sepolia          # or base-mainnet for production

Step 2: Install and run

npm install
node src/index.js

Your storefront is live at http://localhost:3000.

Step 3: Add your first product

curl -X POST http://localhost:3000/products \
  -H "Authorization: Bearer your-strong-random-secret-here" \
  -H "Content-Type: application/json" \
  -d '{
    "path": "/products/my-first-guide",
    "price_usd": 9.99,
    "description": "My first digital product",
    "github_slug": "my-first-guide"
  }'

Step 4: Test the x402 flow

# Get payment requirements
curl http://localhost:3000/products/my-first-guide
Returns 402 with payment requirements JSON
Check the machine-readable catalog
curl http://localhost:3000/products.json | jq .total
Check agent discovery
curl http://localhost:3000/llms.txt

---

Project Structure

your-storefront/
├── src/
│   ├── index.js          # Server entry point (starts Express on port 3000)
│   ├── app.js            # Routes, middleware, x402 paywall logic
│   ├── db.js             # SQLite schema, product CRUD, revenue tracking
│   ├── auth.js           # Bearer token authentication middleware
│   ├── github.js         # Fetch content from GitHub with LRU cache
│   ├── storefront.js     # HTML rendering (listing, detail, admin, JSON-LD)
│   ├── catalog.js        # Enrich DB rows with CATALOG.json metadata
│   ├── sitemap.js        # Generate sitemap.xml
│   └── mcp-server.js     # MCP server (stdio transport)
├── tests/                # Jest test suite (183 tests)
├── deploy.sh             # One-command SSH deployment
├── .env.example          # Environment variable template
├── package.json          # Dependencies + bin entry for MCP server
├── server.json           # Official MCP Registry metadata
└── smithery.yaml         # Smithery registry metadata

---

Configuration Reference

| Variable | Required | Default | Description | |----------|----------|---------|-------------| | DASHBOARD_SECRET | Yes | — | Admin auth token (must be strong) | | AGENT_WALLET_ADDRESS | Yes (for paid) | — | Base wallet for receiving USDC | | GITHUB_TOKEN | Yes | — | PAT for fetching content from GitHub | | GITHUB_REPO | Yes | — | owner/repo containing product .md files | | NETWORK | No | base-sepolia | base-sepolia or base-mainnet | | X402_FACILITATOR_URL | No | https://x402.org/facilitator | x402 facilitator endpoint | | SQLITE_PATH | No | ./dashboard.db | Path to SQLite database | | PORT | No | 3000 | Server listen port |

---

Adding Products

Via API (recommended for automation)

curl -X POST https://your-store.com/products \
  -H "Authorization: Bearer $DASHBOARD_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "path": "/products/my-product",
    "price_usd": 29.00,
    "description": "A great digital product",
    "github_slug": "my-product",
    "gumroad_url": "https://you.gumroad.com/l/my-product"
  }'

Via seed script (bulk)

Create *.meta.json files in seed-products/ and run the seeder:

bash seed-dashboard-incremental.sh http://localhost:3000

Free products

Set price_usd: 0. Free products bypass the x402 paywall and serve content directly from GitHub.

---

Payment Flows

x402 Flow (Agent Buyers)

1. Agent sends GET /products/my-product 2. Server returns 402 with payment requirements:

   {
     "x402Version": 1,
     "accepts": [{
       "scheme": "exact",
       "network": "eip155:84532",
       "maxAmountRequired": "2900000",
       "payTo": "0xYourWallet",
       "asset": "0x036CbD53842c5426634e7929541eC2318f3dCF7e"
     }]
   }
   

3. Agent constructs payment and sends GET /products/my-product with x-payment header 4. Server verifies payment via facilitator 5. Server fetches content from GitHub and delivers it 6. Server settles payment and logs transaction

Fiat Flow (Human Buyers)

Products with a gumroad_url show a "Buy with Card" button on the HTML storefront

Buyers click through to Gumroad/Polar for card/PayPal checkout

Content is delivered via the third-party platform

---

Agent Discovery Layer

Your storefront is automatically discoverable by AI agents through four endpoints:

| Endpoint | Format | Purpose | |----------|--------|---------| | /products.json | JSON | Machine-readable product catalog | | /llms.txt | Plain text | LLM-friendly store description | | /.well-known/agent.json | JSON | Agent capability manifest | | /robots.txt | Plain text | Includes Llms-txt: directive |

Plus Schema.org JSON-LD markup in all HTML pages for search engine rich results.

---

MCP Server

The MCP server exposes your catalog to AI agents via the Model Context Protocol.

Running standalone

node src/mcp-server.js

Tools

| Tool | Parameters | Description | |------|-----------|-------------| | list_products | tag? (string) | Browse catalog, optional tag filter | | get_product | slug (string) | Get single product details | | buy_product | slug (string) | Get purchase URL + x402 instructions |

Claude Desktop config

{
  "mcpServers": {
    "your-store": {
      "command": "node",
      "args": ["/path/to/src/mcp-server.js"],
      "env": {
        "SQLITE_PATH": "/path/to/dashboard.db"
      }
    }
  }
}

---

Deployment

One-command deploy

SSH_KEY=~/.ssh/your_key bash deploy.sh user@your-server

This will: 1. Upload all source files via SCP 2. Run npm install --omit=dev 3. Configure systemd service 4. Set up nginx reverse proxy with security headers 5. Enable HTTPS (auto-detects existing SSL certs)

CI/CD

The included GitHub Actions workflow (deploy.yml) runs tests and deploys on every push to main.

---

Security Hardening

The starter kit includes security measures from a production audit:

F-01: Rate limiting on admin routes (30 req/15 min)

F-02: Bearer token authentication on admin endpoints

F-06: Startup guard — refuses to start with weak/default secrets

F-07: JSON body size limit (10KB)

F-08: Async error handler catches unhandled promise rejections

F-09: Settlement response logging for payment audit trail

nginx: X-Frame-Options, X-Content-Type-Options, CSP, HSTS, Permissions-Policy

---

Customization Guide

Changing the payment network

Edit .env:

NETWORK=base-mainnet  # switches to mainnet USDC

Adding a new discovery endpoint

Add a route in src/app.js following the pattern of /products.json:

app.get('/your-endpoint', (_req, res) => {
  const products = db.getAllProducts();
  const enriched = enrichAll(products);
  res.setHeader('Cache-Control', 'public, max-age=300');
  res.json({ /* your data */ });
});

Custom HTML themes

Edit src/storefront.js. The CSS is inline in template literals — replace the