https://github.com/lnbits/spark_sidecar
Simple sidecar for Spark L2
https://github.com/lnbits/spark_sidecar
Last synced: 2 months ago
JSON representation
Simple sidecar for Spark L2
- Host: GitHub
- URL: https://github.com/lnbits/spark_sidecar
- Owner: lnbits
- Created: 2026-01-13T13:27:44.000Z (5 months ago)
- Default Branch: main
- Last Pushed: 2026-03-24T08:47:02.000Z (3 months ago)
- Last Synced: 2026-04-10T09:00:07.627Z (2 months ago)
- Language: JavaScript
- Size: 270 KB
- Stars: 1
- Watchers: 0
- Forks: 1
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
[](./LICENSE)
[](https://github.com/lnbits/lnbits)
# Spark L2 sidecar
This sidecar exposes a small HTTP API for LNbits to talk to the Spark L2 SDK.
https://www.spark.money/
## Install
```
git clone https://github.com/lnbits/spark_sidecar.git
cd spark_sidecar
npm install
```
## Run
```
chmod +x server.mjs
SPARK_MNEMONIC="bottom bottom bottom bottom bottom bottom bottom bottom bottom bottom bottom bottom" \
SPARK_NETWORK=MAINNET \
SPARK_SIDECAR_PORT=8765 \
SPARK_PAY_WAIT_MS=20000 \
node server.mjs
```
**Spark Multiplicity Setting**
Optional multiplicity tuning for [Spark leaf optimization](https://docs.spark.money/api-reference/wallet/initialize#multiplicity-levels)
Default multiplicity is 3
```
SPARK_MULTIPLICITY=3
```
**Optional API Key**
```
SPARK_SIDECAR_API_KEY="mykey"
```
Set the same key in LNbits as `SPARK_L2_API_KEY`.
If you prefer to provide the mnemonic after startup, omit `SPARK_MNEMONIC` and
POST it to the sidecar:
```bash
curl -X POST http://127.0.0.1:8765/v1/mnemonic \
-H "Content-Type: application/json" \
-d '{"mnemonic":"bottom bottom bottom bottom bottom bottom bottom bottom bottom bottom bottom bottom"}'
```
## Nix (flake)
Build:
```
nix build
```
Run:
```
SPARK_MNEMONIC="bottom bottom bottom bottom bottom bottom bottom bottom bottom bottom bottom bottom" \
SPARK_NETWORK=MAINNET \
SPARK_SIDECAR_PORT=8765 \
SPARK_PAY_WAIT_MS=20000 \
nix run
```
Notes:
- The flake includes `flake.nix` and `flake.lock`. Commit both.
- The `result` symlink from `nix build` should not be committed.
## Endpoints
- `POST /v1/mnemonic`
- `POST /v1/balance`
- `POST /v1/invoices`
- `POST /v1/payments`
- `GET /v1/invoices/stream` (SSE stream of paid Lightning receive requests)
- `GET /v1/invoices/{id}`
- `GET /v1/payments/{id}`
### Invoice Stream
The stream endpoint emits Server-Sent Events when a Lightning invoice is paid.
Example:
```bash
curl -N http://127.0.0.1:8765/v1/invoices/stream
```
Each event payload is a JSON object:
```json
{
"checking_id": "",
"payment_hash": "",
"status": "LIGHTNING_PAYMENT_RECEIVED"
}
```
Optional tuning:
- `SPARK_STREAM_KEEPALIVE_MS` (default `15000`)
- `SPARK_STREAM_HEARTBEAT_MS` (default `30000`)
- `SPARK_TRANSFER_LOOKUP_CONCURRENCY` (default `20`)
- `SPARK_TRANSFER_QUEUE_MAX` (default `5000`)
- `SPARK_INVOICE_POLL_MS` (default `2000`)
- `SPARK_INVOICE_POLL_LIMIT` (default `100`)
- `SPARK_INVOICE_CACHE_TTL_MS` (default `3600000`)
## Powered by LNbits
[LNbits](https://lnbits.com) is a free and open-source lightning accounts system.
[](https://shop.lnbits.com/)
[](https://my.lnbits.com/login)