Accept Bitcoin Lightning payments on Hugo sites. Includes Netlify proxy, payment page template, and analytics CLI.
CLI dashboard with mock data
Hugo payment page
npm install
./bin/v4v init # Interactive setup wizardOr manually create a .env file (see .env.example):
NWC_CONNECTION_STRING=nostr+walletconnect://...
V4V_SITE_URL=yourdomain.com./bin/v4v init # Interactive setup wizard
./bin/v4v status # Check connection and config status./bin/v4v report # Basic payment summary
./bin/v4v report --usd # Include USD values
./bin/v4v report --by-essay # Breakdown by essay/page
./bin/v4v report --time-series # Monthly trend
./bin/v4v report --compare # Compare to previous period
# Date filtering
./bin/v4v report --since 7d # Last 7 days (also: 2w, 1m, 3mo, 1y)
./bin/v4v report --from 2024-01-01 # From specific date
./bin/v4v report --from 2024-01-01 --to 2024-01-31
# Output formats
./bin/v4v report --format json # JSON output
./bin/v4v report --format csv # CSV to stdout
./bin/v4v report --export data.csv # CSV to file./bin/v4v dashboard # Start web dashboard (port 3000)
./bin/v4v dashboard -p 8080 # Custom port
./bin/v4v dashboard --mock # Use mock data for demosDashboard features:
- Time range filtering (7d, 30d, 90d, 12mo, All)
- Sortable source table with drill-down
- Weekly trend chart
- Mobile responsive
- URL state persistence (
?range=7&sort=sats)
./bin/v4v cache # Show cache stats
./bin/v4v cache --clear # Clear cache
./bin/v4v cache --rebuild # Clear and fetch all transactions freshImportant: The CLI caches transactions locally and only fetches new ones on subsequent runs. If you're missing older payments, run --rebuild to fetch your complete transaction history.
Use --rebuild when:
- Payments you know exist aren't showing up in reports
- You've cleared or corrupted the cache
- You want to ensure you have complete data
./bin/v4v --no-color # Disable colored output
./bin/v4v --help # Show help
./bin/v4v --version # Show versionColored output respects the NO_COLOR environment variable.
| Environment Variable | Description | Default |
|---|---|---|
NWC_CONNECTION_STRING |
NWC connection URL (required) | - |
V4V_SITE_URL |
Site URL for filtering payments (required) | - |
V4V_RSS_URL |
RSS feed URL for essay titles | https://{site}/feed.xml |
NWC_TIMEOUT |
NWC request timeout in ms | 120000 |
V4V_MAX_BATCHES |
Max transaction batches to fetch (~10 tx/batch) | 100 |
V4V_BATCH_DELAY |
Delay between batches in ms | 300 |
- Connects to your Alby Hub (or any NWC provider) via Nostr Wallet Connect
- Fetches incoming Lightning payments and caches them locally (
.v4v-cache.json) - On subsequent runs, only fetches transactions newer than the cache
- Filters for V4V payments (containing your site URL in description)
- Fetches essay titles from your site's RSS feed for friendly display
- Aggregates and displays analytics by essay, time period, etc.
Note: If you have many non-V4V transactions (Nostr zaps, podcast streaming, etc.), they fill up the cache but are filtered out of reports. Use v4v cache --rebuild to ensure complete history if payments seem missing.
Accept V4V payments on your Hugo site deployed to Netlify. This repo includes:
- Netlify proxy - LNURL-pay edge functions for discovery, invoice generation, and status polling
- Hugo template - Payment page with amount selection and QR codes
- Theme-agnostic CSS - Customizable via CSS variables
# Quick start
cp -r proxy/netlify/* your-site/netlify/
cp -r hugo/layouts/v4v your-site/layouts/
cp hugo/assets/css/v4v.css your-site/assets/css/
npm install @getalby/sdk bolt11See docs/HUGO_SETUP.md for complete setup instructions.
npm test # Run tests
./bin/v4v dashboard --mock # Test dashboard with mock dataMIT