close
Skip to content

Sidecar Quickstart

The Lexe Sidecar SDK presents a simple JSON API for developers to control their self-custodial, always-online Lexe node which can send and receive payments over the Lightning Network. Running the lexe-sidecar binary spins up a local webserver (the "sidecar") at http://localhost:5393 which accepts REST requests and proxies them to your Lexe node. By making simple HTTP requests like

GET  http://localhost:5393/v2/node/node_info
POST http://localhost:5393/v2/node/create_invoice
POST http://localhost:5393/v2/node/pay_invoice
GET  http://localhost:5393/v2/node/payment

you can programmatically control your Lexe node. Your app can be written in any language, and is portable to any environment where lexe-sidecar can run.

Install

Official install script

The easiest way to install lexe-sidecar is using the official install script:

curl -fsSL https://lexe.app/install-sidecar.sh | sh

This will install the lexe-sidecar binary at ~/.local/bin and add it to your PATH. To use the sidecar in your current shell, you may need to run:

# For sh/bash/zsh
source ~/.local/bin/env
# For fish
source ~/.local/bin/env.fish

On Replit?

See Lexe Sidecar on Replit for a one-prompt agent setup that handles installation, credentials, and workflow configuration.

Alternative installation methods

If you prefer manual installation or need to build from source:

  1. Download a precompiled binary from the Releases page
  2. Build the binary from Rust source: see Build from source for instructions

Configure credentials

The sidecar authenticates with one of the following:

  1. Client credentials: scoped and revocable, well-suited for controlling your own existing wallet, or for building applications with limited access to other people's wallets, including charging for services via pull payments.
  2. Root seed: the master secret of a Lexe wallet. Typically used only if the wallet was created locally, and not via the Lexe mobile app.

See the Authentication page for more details.

The sidecar's default credentials are configured via environment variables, CLI arguments, or a .env file in the working directory. Per-request credentials passed in the Authorization header take precedence over the default.

Control an existing wallet (client credentials)

Get client credentials from the Lexe mobile app

  1. Download the Lexe mobile app (iOS, Android)
  2. Menu > "Client credentials" > "Create credentials"
  3. Copy the credentials string

Set the default credentials

Set LEXE_CLIENT_CREDENTIALS in your environment (or LEXE_CLIENT_CREDENTIALS_PATH to point at a file), or pass --client-credentials / --client-credentials-path to the sidecar binary:

# Set in environment
$ export LEXE_CLIENT_CREDENTIALS="eyJsZXhlX2F1dGhfdG9rZ...TA0In0"

# Or pass directly to the sidecar binary
$ lexe-sidecar --client-credentials-path /path/to/client_credentials.txt

A .env file in the sidecar's working directory is also auto-loaded.

Use a new or existing root seed from local disk

Create a new wallet via the CLI

The simplest way to create a Lexe wallet for use with the sidecar is via the Lexe CLI:

$ lexe init

This generates a new root seed, signs you up with Lexe, and provisions your Lightning node. The seed is persisted to ~/.lexe/seedphrase.txt, and the sidecar will pick it up automatically.

Use an existing root seed

If no root seed is configured via env or CLI, the sidecar falls back to ~/.lexe/seedphrase.txt. To use a root seed at a different location, or to pass the seed value directly, set LEXE_ROOT_SEED in your environment (or LEXE_ROOT_SEED_PATH to point at a file), or pass --root-seed / --root-seed-path to the sidecar binary:

# Set the seed value directly in environment
$ export LEXE_ROOT_SEED="0123...abcd"

# Or point at a file (hex or seedphrase formats are both OK)
$ export LEXE_ROOT_SEED_PATH="/Users/satoshi/secrets/lexe_root_seed.txt"

# Or pass directly to the sidecar binary
$ lexe-sidecar --root-seed-path /Users/satoshi/secrets/lexe_root_seed.txt

Control multiple 3rd-party wallets (per-request credentials)

To control a different wallet per request, pass ClientCredentials via the Authorization header, formatted as Bearer <credentials>:

curl http://localhost:5393/v2/node/node_info \
    -H "Authorization: Bearer eyJsZXhlX2F1dGhfdG9rZ...TA0In0"

This pattern is useful for services that operate on multiple users' wallets. For example:

  • A payment gateway can collect each user's receive credentials and create invoices on their behalf.
  • A subscription service can charge users via pull payments using credentials those users granted.

Per-request credentials take precedence over the sidecar's default credentials.

Run the sidecar

Run the sidecar:

$ lexe-sidecar

Test your setup by making a request to it:

$ curl http://localhost:5393/v2/node/node_info | jq .
{
  "version": "0.7.9",
  "measurement": "6d6ae19f2a82167abecd7bbe834e417a1b3c9c8971d08bd05b24533de21bf3f1",
  "user_pk": "63ad1661bfc23ad25f5bcc6f610f8fd70d7426de51be74766c24e47f4b4fcfca",
  "node_pk": "02e4d8f86591eb2ce59a787e2a5abb83278c86198ac22854e9e3cf365cf8d9730f",
  "balance": "95507",
  "lightning_balance": "40000",
  "lightning_sendable_balance": "40000",
  "lightning_max_sendable_balance": "39824.777",
  "onchain_balance": "55507",
  "onchain_trusted_balance": "55507",
  "num_channels": 1,
  "num_usable_channels": 1
}

Using the sidecar

With the sidecar running, you can use HTTP requests to create invoices, send payments, and more. See the REST API Reference for the full list of endpoints.

Example: Create a Lightning invoice.

$ curl -X POST http://localhost:5393/v2/node/create_invoice \
    --header "content-type: application/json" \
    --data '{
        "expiration_secs": 3600,
        "amount": "5000",
        "description": "Initial deposit"
    }' \
    | jq .
{
  "index": "0000001772349167284-ln_16ec06bf32459f0bd3fbbf2fdaace70b60dcadbbfb170de097edd5e515d7ac18",
  "invoice": "lnbc50u1p568eh0dqgf36kucmg...",
  "description": "Initial deposit",
  "amount": "5000",
  "created_at": 1772349167000,
  "expires_at": 1772352767000,
  "payment_hash": "16ec06bf32459f0bd3fbbf2fdaace70b60dcadbbfb170de097edd5e515d7ac18",
  "payment_secret": "1e5a7b807fd38c7133898212e46558be0686971b36787b37f4e53284a9c0bc98"
}

The invoice string is what you give to the payer. The index identifies this payment for follow-up queries (e.g., GET /v2/node/payment?index=…).

Example: Pay a Lightning invoice.

$ curl -X POST http://localhost:5393/v2/node/pay_invoice \
    --header "content-type: application/json" \
    --data '{
        "invoice": "lnbc...",
        "personal_note": "Open-source donation"
    }' \
    | jq .
{
  "index": "0000001744926842458-ln_e1f8e7fa3f3b43eb65afe4897ca1c63688636ba0a23b3011710e433b51bb3f9a",
  "created_at": 1744926842458
}

Receiving payment notifications with webhooks

When a payment is finalized (completed or failed), the sidecar can POST a JSON notification to a webhook URL of your choosing. This is useful for tracking payment status without polling. For payments initiated via the sidecar (both sends and receives), the sidecar tracks pending payments across restarts and retries failed deliveries up to 3 times with exponential backoff before giving up.

See the webhooks page for details.

Vibe code your Lightning app

You're all set - it's time to build your Lightning app! Here's a prompt which allowed us to "vibe code" a fully functional Lightning tip page in 3 minutes with Claude via goose. Claude Code, Codex, etc work well too. Since this prompt tells the AI to run the sidecar as a subprocess of your app, stop any running sidecar first. Also be sure to change the project names and paths to match your own machine.

Build a tip page powered by the Lexe API. This will be a python web service that
renders a simple tip page for visitors to our site. When a visitor taps the tip
button, the backend will query the Lexe API for a new Lightning invoice and
render it as a QR code on the frontend. The frontend will repeatedly poll the
backend for the invoice status until it's paid. Once the invoice is paid,
it will go the success page and show a confetti animation.

The backend should spawn the Lexe sidecar as a subprocess. The sidecar will
expose the Lexe API at `http://localhost:5393`. You can find the sidecar binary
at </Users/satoshi/.local/bin/lexe-sidecar>. You can find the Lexe API docs
at: </Users/satoshi/dev/lexe-sidecar-sdk/README.md>. Make sure you read this
first so you understand how all the pieces fit together.

We're running on macOS and already have python 3.12 installed. You're already
in the project directory </Users/satoshi/dev/myproject>. Try to use the python
standard library as much as possible. Create a new python virtual environment to
keep all the dependencies isolated. The frontend can be a simple HTML page
rendered by the backend with some basic JS+CSS for polling and rendering the QR
code. Serve the backend on port 8080.

Don't ask for permission, just start coding.

Demo: See this prompt in action:

Watch the video