Environments

Coal runs two environments: development (local) and production. The backend is a Next.js API application; the frontend is a separate Next.js application. Both must be running locally for full end-to-end development.

Environment Overview

Base URL in Code

1// Use the environment variable — never hardcode URLs
2const COAL_API_URL = process.env.NEXT_PUBLIC_API_URL ?? 'http://localhost:3001';
3
4// Example request
5const res = await fetch(`${COAL_API_URL}/api/checkout/init`, {
6  method: 'POST',
7  headers: { 'Content-Type': 'application/json' },
8  body: JSON.stringify({ slug: 'my-product' }),
9});

Local Development Setup

Prerequisites

• Node.js 20+
• A PostgreSQL database (we use Neon — the free tier is sufficient)
• Optional: an Upstash Redis instance for rate limiting (the app runs fine without it using an in-memory fallback)

1. Clone the Repository

1git clone https://github.com/your-org/coal.git
2cd coal

2. Install Dependencies

1# Install backend dependencies
2cd backend && npm install
3
4# Install frontend dependencies
5cd ../frontend && npm install

3. Configure Environment Variables

Copy the example files and fill in your values:

1cp backend/.env.example backend/.env.local
2cp frontend/.env.example frontend/.env.local

Then edit each file — see the variable reference tables below.

4. Push the Database Schema

1cd backend
2npx prisma db push

This creates all tables in your PostgreSQL database. No migration files are generated — db push is used for rapid development iteration.

5. Start Both Servers

1# Terminal 1 — backend API on port 3001
2cd backend && npm run dev
3
4# Terminal 2 — frontend on port 3000
5cd frontend && npm run dev

Open http://localhost:3000 to see the app.

Environment Variables

Backend (backend/.env.local)

Frontend (frontend/.env.local)

Chain Configuration

Coal's backend verifies payments on the Base blockchain (an Ethereum L2). Two networks are supported:

During development, set CHAIN_ENV=testnet in both your backend and frontend .env.local files. This routes all on-chain verification to Base Sepolia so you can test with a non-production settlement token without spending real funds.

Important: Your settlement token contract address can differ between mainnet and testnet. Always set SETTLEMENT_TOKEN_ADDRESS and NEXT_PUBLIC_SETTLEMENT_TOKEN_ADDRESS to the correct contract for your current CHAIN_ENV. Legacy MNEE_* names still work if you already use them, but new integrations should prefer the settlement-token variables.

MoonPay uses a server-signed funding session behind the scenes. The frontend only needs the publishable key to show the card path. The backend still needs:

• MOONPAY_PUBLISHABLE_KEY
• MOONPAY_SECRET_KEY
• MOONPAY_WEBHOOK_API_KEY
• MOONPAY_ENV

Coal stays non-custodial: MoonPay funds the payer wallet first, and Coal only completes the merchant payment after the payer signs the onchain transfer from that wallet.

Production Deployment

Coal is designed to deploy on Vercel. Both the backend and frontend are standard Next.js applications and can be deployed independently.

Set all environment variables in Vercel → Project → Settings → Environment Variables. Never commit .env.local or any file containing secrets to version control.

For the cron job (/api/cron/verify-payments), configure a Vercel Cron or external scheduler to POST to that endpoint every minute with:

1Authorization: Bearer <your CRON_SECRET>

The cron job is what transitions sessions from verifying to confirmed — if it stops running, payments will remain in verifying indefinitely.