Rovereto, Tuesday 17 November 2026 · Year XIII, n. 321 itende
Bitcoin Valley
ContentsClose

Dispatches from the valley where you pay in bitcoin.

For people who take things apart

The software

This site runs on bitmentor, under the GNU AGPLv3 licence (other licences, such as MIT, on request from the authors): github.com/mammadori/bitmentor. If your town wants to do the same, the code is there: it's our legacy. Name, colours, history and pages live in a folder, and can be changed without touching the code.

Try it now with your town: type the name, watch the site change, download your folder ready to go.

Design choices

The server never sees the recovery words and cannot spend. There are no spending keys anywhere in the system.

The server doesn't even see the sales. The till lives on the shop's phone or computer: it requests the invoice directly from the shopkeeper's Lightning address, checks the payment with their wallet and keeps the history there, with the copies the shopkeeper downloads. On-chain is an experimental feature, off until the community switches it on (the Valley keeps it on): whoever wants it puts their public key in the till, and the addresses are created there.

A shop with a Lightning address gets paid even if the server goes down: the address belongs to its wallet, and a QR code of the address printed separately goes on working. The site's sign doesn't: its QR code opens the shop's page, which lives on the server.

Suspension takes a shop off the map and leaves its till alone. Whoever runs the site has no way of blocking anyone's takings.

What's inside

Part Technology
Site and panel Django, Postgres, Caddy
Till In the browser: it requests the invoice from the shop's Lightning address (LNURL-pay) and checks the payment with LUD-21 verify
Non-custodial takings Any Lightning address that answers LUD-21 verify from its own domain and to the browser; for a small shop, a self-custodial wallet on Spark (which ones we've tried)
On-chain Experimental, off by default: on the till's phone or computer, extended public key or fixed address
Login LNURL-auth, or a link by email
Map Leaflet, OpenStreetMap, no key
Open data NIP-05, shops and events signed on Nostr, /shops.json

There is no Bitcoin node and no payment server on the server: nothing to sync, no channels, no wallet API keys. Sales stay on the till's phone or computer.

Installation

What you need To try it For a real site
Software Python 3.14 Linux with Docker
Machine Your own computer Just one: 1 or 2 CPUs, 2 GB of RAM
Network Nothing A domain name pointing to it, ports 80 and 443 open

To try it (5 minutes)

On your own computer, with an example community and made-up shops:

python3 -m venv .venv && .venv/bin/pip install -r requirements.txt
export SECRET_KEY=prova DEBUG=1 && .venv/bin/python manage.py migrate && .venv/bin/python manage.py demo_data
.venv/bin/python manage.py runserver

For a real site (one machine)

One machine is enough, with what the table says: Caddy fetches the certificates by itself.

git clone https://github.com/mammadori/bitmentor.git && cd bitmentor && cp -r examples/community ../my-community
cp .env.example .env && for k in SECRET_KEY POSTGRES_PASSWORD WEB_DB_PASSWORD; do sed -i "s/^$k=.*/$k=$(openssl rand -hex 32)/" .env; done && chmod 600 .env

In .env write the name with SITE_HOST, your community's path with COMMUNITY_DIR and your IP address in DEV_ALLOWED_IPS. Then:

docker compose up -d
You start on signet, and who can see the site

You start on signet, the test network, where everything works the same and the coins are worth nothing; mainnet is a step later.

The site starts in development mode: only the addresses listed in DEV_ALLOWED_IPS can see it. SITE_MODE=production opens it to everyone and works only on mainnet. manage.py preflight tells you what's still missing, from email to mainnet. To update: git pull && docker compose up -d --build.

From then on the merchants manage by themselves: each one enters the Lightning address of their own wallet. If you're coming from another system, manage.py import_shops file.json brings in the list of shops. Optional features, from Telegram to Nostr, are switched on from .env or from community.yml; the two experimental ones, on-chain at the till and uploading to OpenStreetMap, stay off until the community switches them on. Which wallets to suggest to shops is in docs/wallets.md. The list of features is in the README, with step-by-step instructions and the version with images and CI for larger setups.

Your community

community.yml      name, contacts, languages, route, events
theme/             fonts, colours, logo, images
pages/<language>/  pages in Markdown, with live data
templates/         header and footer, if you want them different
data/              your numbers

This folder is the only thing that differs from one community to the next. The Valley in your town prepares one for you, in your browser.

Open data

Blossom: files by fingerprint

The site's files (photos, documents, the copy of the site) can also be requested by their SHA-256 fingerprint, as a read-only Blossom server does: https://bitcoinvalley.eu/blossom/<sha256>.

Anyone can check that the bytes match the fingerprint and keep a copy on their own Blossom server; if you want to copy them all, start from /blossom/list, the list with the fingerprint, size and address of every file. Nothing is uploaded and nobody's permission is needed.

It's the technical piece of digital immortality: a file someone has copied stays reachable, with the same fingerprint, even from another address. It lasts as long as someone keeps it: the site makes the files available, and whoever wants to makes the copies.

Don't trust, verify

The PDF of Satoshi's text you'll find here is the same one etched into the blockchain. With your own node:

seq 0 947 | (while read -r n; do bitcoin-cli gettxout 54e48e5f5c656b26c3bca14a8c95aa583d07ebe84dde3b7dd4a78f4e4186e713 $n | jq -r '.scriptPubKey.asm' | awk '{print $2 $3 $4}'; done) | tr -d '\n' | cut -c 17-368600 | xxd -r -p | sha256sum

The output should be b1674191a88ec5cdd733e4240a81803105dc412d6c6708d53ab94fc248f4f553, as for our file.

The ledger's sums can be redone like this:

awk -F, 'NR>1{s+=$2} END{print s}' registro-mesi.csv

That comes to 5143.

The site itself can be taken away: a whole copy, with its fingerprints and signature, to put back up anywhere.

The open data on the page: the ledger Using it in a shop