Introduction
============

The Offline Bitcoin ATM is a coin-operated Bitcoin Lightning ATM built around an
ESP32 microcontroller. A user inserts physical euro coins; the firmware tallies
their value and renders an `LNURL-withdraw <https://github.com/lnurl/luds>`_ QR
code directly on the e-paper display. The user scans it with any Lightning wallet
to withdraw the equivalent amount of bitcoin.

How it works offline
--------------------

The ATM never needs an internet connection while it is running. Instead of
contacting a server to create each withdraw link, it generates the LNURL-withdraw
payload **locally** using the `LNbits FOSSA <https://github.com/lnbits/fossa>`_
protocol:

1. On setup you pair the device with an LNbits wallet + FOSSA extension, which
   gives the ATM a shared secret and an API base URL.
2. When coins are inserted, the firmware encrypts the amount and a nonce into a
   compact, signed payload and encodes it as a bech32 ``LNURL`` string.
3. That string is shown as a QR code. When the user's wallet follows it, the
   *wallet's* internet connection talks to your LNbits server, which validates
   the payload and pays out — so only the user's phone needs to be online, never
   the ATM.

This is what lets the ATM operate in places without WiFi, while still settling
real Lightning payments.

State machine
-------------

The firmware runs a simple loop: it sits **idle** showing a welcome (or the
optional BlockClock display), counts coins while they are being inserted, and once
the user presses the button it shows the **withdraw** QR code. See
:doc:`development/index` for the architecture.

Gallery
-------

.. figure:: assets/photos/ATM_Photo_1.jpg
   :width: 100%
   :alt: Assembled Offline Bitcoin ATM

   An assembled Offline Bitcoin ATM.

.. figure:: assets/photos/ATM_Photo_2.jpg
   :width: 100%
   :alt: Offline Bitcoin ATM, alternate view

More construction photos of the Waveshare-ESP32 build are in
:doc:`hardware/index`.

Special thanks
--------------

This project stands on the shoulders of several others:

- **@21isenough** and contributors — for the 3D models and inspiration, via the
  `Raspberry-Pi based Lightning ATM <https://github.com/21isenough/LightningATM>`_.
- **LNbits, Ben Arc and Stepan Snigirev** — for the cryptography that makes this
  ATM work without an internet connection, via the
  `FOSSA ATM repository <https://github.com/lnbits/fossa>`_
  (`LNbits homepage <https://lnbits.com/>`_).
- **Axel Hamburch** — for the very detailed German-language guide on assembling
  the electronics, at the
  `Ereignishorizont blog <https://ereignishorizont.xyz/lightning-atm/>`_.
- **@marcelhino** — for the
  `OrangeClock project <https://github.com/marcelhino/orangeclock>`_, whose code
  was used as reference for the "BlockClock" idle display mode.

Contact & support
-----------------

If you need help, reach out on Nostr:
``npub1z9n5ktfjrlpyywds9t7ljekr9cm9jjnzs27h702te5fy8p2c4dgs5zvycf``.

If this software and guide were useful to you, feel free to send some sats —
message on Nostr for a Lightning address.