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

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 \x3Cyour-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

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:

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

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 \x3Cstyle> 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.