Connect LND to Clams with a Read-Only LNC Pairing Phrase

Clams connects to LND nodes with Lightning Node Connect (LNC), using a 10-word pairing phrase. The easiest way to create one is Lightning Terminal, Lightning Labs' web dashboard for LND, where a few clicks give you a read-only phrase. This guide shows those clicks, then the Clams commands that connect and sync your node.

What Clams Imports From LND

• Routing fee income from every forwarded payment
• Channel opens and closes, including the on-chain fees you paid
• Lightning invoices and payments
• On-chain transactions in your node's wallet, including channel funding

Before You Start

What You'll Need:

• An LND node that is running and synced
• Lightning Terminal connected to that node (setup below)
• Clams installed and set up

If you have not set Clams up yet, install it and run clams init, which signs you in and creates your workspace and profile:

curl -fsSL https://clams.tech/install.sh | sh
clams init

Get Lightning Terminal

Lightning Terminal (litd) connects to your LND node and gives you a web UI for it. If you already use it, skip to the next section. Otherwise, download and run it yourself or install it from your node platform's app store.

Option 1: Download and Run It Yourself

1. Download the latest release for your operating system from Lightning Terminal's GitHub releases. Each release only works with recent LND versions (current releases need LND 0.19 or newer), so check the compatibility notes against your node.
2. Add this line to your node's lnd.conf, then restart LND:

rpcmiddleware.enable=true

3. If LND runs on the same machine with its default data directory on mainnet, Lightning Terminal finds it automatically and you can skip this step. Otherwise, create a lit.conf that points at your node's gRPC address, TLS certificate and admin macaroon:

lnd-mode=remote
remote.lnd.rpcserver=127.0.0.1:10009
remote.lnd.tlscertpath=/path/to/tls.cert
remote.lnd.macaroonpath=/path/to/admin.macaroon

4. Start Lightning Terminal with a password of your choice (at least 8 characters), then open https://localhost:8443 and log in. Your browser will warn about the self-signed certificate; that is expected for a local install.

./litd --uipassword=YOUR_PASSWORD

To run Lightning Terminal on a different computer from LND, copy tls.cert and admin.macaroon across, use your node's address in remote.lnd.rpcserver, and set LND up to accept remote connections as described in the Quickstart of Lightning Labs' remote LND guide. That guide also shows where lit.conf lives on each operating system.

Lightning Terminal needs the admin macaroon, but Clams never sees it. Clams only gets the read-only pairing phrase.

Option 2: Install It on Start9, Umbrel or myNode

All three platforms package Lightning Terminal and connect it to the LND node they already run:

• Start9: install Lightning Terminal from the StartOS Marketplace and run its Create Password task (copy the password, as it is shown only once). Then start it and open its Web UI. If you lose the password, the Reset Password action makes a new one.
• Umbrel: install Lightning Terminal from the Umbrel App Store. It needs Umbrel's Lightning Node app, which runs LND.
• myNode: Lightning Terminal comes with myNode. Open it from the Lightning page, and use the password shown there under show password, not your myNode password. See myNode's Lightning Terminal guide.

Create a Read-Only Pairing Phrase

A pairing phrase is 10 words that let an app reach your node over LNC. The session's permissions set what that app can do, so always choose Read Only for Clams.

1. In Lightning Terminal, open Lightning Node Connect in the left menu and click Create a new session:

2. Give the session a label (for example Clams), set Permissions to Read Only, then click Submit:

3. Check that the new session's type says Read-Only, then click the copy icon next to it. This copies the 10-word pairing phrase:

Use the phrase within 10 minutes. A new session must make its first connection within 10 minutes, or it expires unused. If that happens, delete it and create a new one.

Connect LND to Clams

1. Set your profile's currency and cost basis method. Clams needs both before it can sync. Pick your own fiat currency, and FIFO, LIFO, HIFO, LOFO or AVG_COST as the method:

clams profiles set --fiat-currency USD --gains-algorithm FIFO

2. Set up a Bitcoin chain source. Clams reads on-chain data through a chain source, set up once per profile. If you've used Clams before, you likely have one (clams chain-sources list to check). Otherwise add one and select it, using Blockstream's public server or your own node:

clams chain-sources create --label bitcoin --kind Electrum --url ssl://electrum.blockstream.info:50002 --select

3. Create the LND connection, pasting your pairing phrase in place of YOUR_PAIRING_PHRASE. Keep the command on one line:

clams connections create --label lnd --kind Lnd --configuration '{"transport":"lnc","config":{"pairing_phrase":"YOUR_PAIRING_PHRASE"}}'

4. Sync your node's history and process it into journal entries:

clams connections sync lnd
clams journals process

The first sync imports your full history, so it can take a while on a busy routing node. Re-run both commands anytime to pull in new activity.

What Read Only Allows

A Read Only session lets Clams see balances, channels, payments and forwards, but it cannot open channels, make payments or move funds. Your keys never leave your node.

LNC traffic passes through a relay run by Lightning Labs, but it is end-to-end encrypted between your node and Clams, so the relay cannot read it.

You can revoke the session at any time with the red X next to it in Lightning Terminal. Clams can no longer sync that connection after that.

Tips

• Keep your node online when you sync. Clams reads from your node at sync time, so Lightning Terminal and LND need to be running when you run clams connections sync.
• Multiple nodes: create a separate session and connection for each node, with descriptive labels (for example lnd-routing and lnd-merchant), then sync them all with clams connections sync --all.

Next Steps

Generate a capital gains report:

clams reports capital-gains --format csv

Check your node's profitability with the Lightning node profitability report. It shows routing income, liquidity and on-chain fees, net result and annualized yield for the connection. Add --channels for a per-channel breakdown:

clams reports lightning-pnl --connection lnd

For an overview of what Clams tracks for LND, see the LND integration page.

Get Help

For help connecting your node:

• Join our Discord community for quick assistance
• Email us directly: support@clams.tech

Common issues:

• Sync can't connect: Make sure LND and Lightning Terminal are both running, and that you used the phrase within 10 minutes of creating the session
• Session shows Admin: Delete it and create a new one with Permissions set to Read Only
• Command errors in the terminal: Check the whole command is on one line, with the single quotes around the JSON intact

About LND: LND is a widely used Lightning Network implementation, developed by Lightning Labs. Lightning Terminal is its companion dashboard for liquidity management and Lightning Node Connect.

About Clams: Clams is purpose-built Bitcoin accounting software that provides accurate cost basis tracking and exports reports like capital gains for individuals, businesses and enterprises.