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

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 Get
Architecture Overview
Quick Start (15 Minutes)
Project Structure
Configuration Reference
Adding Products
Payment Flows
Agent Discovery Layer
MCP Server
Deployment
Security Hardening
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 <your-repo>
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)

Agent sends GET /products/my-product

Server returns 402 with payment requirements:

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

Agent constructs payment and sends GET /products/my-product with x-payment header
Server verifies payment via facilitator
Server fetches content from GitHub and delivers it
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:

Upload all source files via SCP
Run npm install --omit=dev
Configure systemd service
Set up nginx reverse proxy with security headers
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 <style> blocks with your brand colors.

Multiple storefronts

Run multiple instances with different SQLITE_PATH and PORT values behind the same nginx.

What's Next

Polar.sh integration: Run python3 create-polar-products.py to bulk-create products on Polar.sh
MCP registry: Register your server on mcp.so, smithery.ai, and the official MCP registry
Bundle products: Create bundle meta.json files with an includes array
Analytics: Check /metrics (admin) for revenue, costs, and P&L

Built with the x402 protocol. Payments in USDC on Base.

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

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

What You'll Learn

Full Guide

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

Table of Contents

What You Get

Architecture Overview

Quick Start (15 Minutes)

Prerequisites

Step 1: Clone and configure

Step 2: Install and run

Step 3: Add your first product

Step 4: Test the x402 flow

Project Structure

Configuration Reference

Adding Products

Via API (recommended for automation)

Via seed script (bulk)

Free products

Payment Flows

x402 Flow (Agent Buyers)

Fiat Flow (Human Buyers)

Agent Discovery Layer

MCP Server

Running standalone

Tools

Claude Desktop config

Deployment

One-command deploy

CI/CD

Security Hardening

Customization Guide

Changing the payment network

Adding a new discovery endpoint

Custom HTML themes

Multiple storefronts

What's Next