Repository navigation
v2.6.0 — Device WebSocket channel for Bolt Card taps
What's new since v2.5.4
Device WebSocket channel (v2.6.0)
Bolt Card taps previously reached the server via a fresh HTTPS POST per tap.
Some consumer routers fail new TLS connections in phases (any destination)
while established connections keep working in both directions — on such a
router the NFC payment failed exactly when the phase was bad, while QR
payments (which only ride the established core WebSocket) kept working.
New endpoint: /zapbox/api/v1/ws/nfc/{device_id} — a persistent WebSocket the
device sends events over. A tap now rides an established channel that was
opened once at boot and needs no fresh TLS connection.
{"event": "lnurlw", ...}from the device runs the same payment logic as
the HTTP endpoint (extracted into a sharedprocess_nfc_lnurlw())- The reply (
lnurlw_resultwithstatus/detail/request_id) goes back on
the same socket; handling runs in a spawned task so the channel stays
responsive, replies are serialized per connection - The relay trigger on settlement still arrives via the core WebSocket
(/api/v1/ws/{device_id}) exactly as for QR payments — server pings, the
"No active ZapBox connections" check, and the PIN flow (pin_requiredvia
core WS,pin_submitvia HTTPS) are all unchanged - The HTTP endpoint
POST /zapbox/api/v1/nfc/{device_id}remains as fallback
for older firmware and for when the channel is down — compatible in both
directions
Compatibility
| Component | Required version |
|---|---|
| LNbits | ≥ 1.4.0 |
| ZapBox firmware | any — older firmware keeps using the HTTP endpoint; the channel needs a firmware with serviceNfcWebSocket() (branch fix/network-stability or later) |
| Reverse proxy | must pass WebSocket upgrades on /zapbox/... (usually already configured host-wide for /api/v1/ws/...) |
Upgrade notes
No database migration. Uninstall the old extension in LNbits and install
v2.6.0 so the new module is loaded. Devices reconnect automatically; firmware
with channel support logs Device channel connected – taps use the persistent channel once the new endpoint is live.