Lightspark Connect Quickstart

Lightspark Connect enables you to interact with the Lightning Network without the complexity that typically comes with it. Lightspark handles the intricacies of nodes, channels, liquidity management, security, backups and routing and provides you a simple API interface so you can focus on building core application features. Whether you're building a marketplace, a payments solution, or any platform that benefits from instant, low-cost bitcoin transactions, Lightspark Connect provides the tools you need to get up and running quickly.

In this guide we'll walk through sending your first Lightning payment with Lightspark. For those of you that need a Lightning primer, please review An Introduction to the Lightning Network.

Getting Started with Lightspark Connect

Let's get started with Lightspark Connect, follow these steps to set up your development environment:

Generating Credentials

To use Lightspark Connect, you'll need to generate API credentials. These credentials are used to authenticate your requests to the Lightspark API. To generate your credentials:

Sign up for a Lightspark account
Navigate to the Developers > API Config section in your dashboard
Click on "New Token" then choose a name, the Test environment and Write Permissions
Save your Client ID and Client Secret securely - you'll need these to initialize the client library
Copy the Node ID and Node Password from the API Config page. For test mode, you'll use the default node password 1234!@#$, for live mode, you'll set the node password when you first enable live mode.

Never share your Client Secret or commit it to version control. It's recommended to use environment variables or a secure secret management system to store these credentials.

Installing the SDK

First, you'll need to install the Lightspark SDK. Here's how to do so in different languages:

npm install @lightsparkdev/lightspark-sdk

Initializing the Client Library

With your SDK installed and credentials in hand, you're ready to initialize the Lightspark client in your application. Here's how you can do so in Typescript:

import {
  AccountTokenAuthProvider,
  LightsparkClient,
} from "@lightsparkdev/lightspark-sdk";

const API_TOKEN_CLIENT_ID = process.env.LIGHTSPARK_API_TOKEN_CLIENT_ID;
const API_TOKEN_CLIENT_SECRET = process.env.LIGHTSPARK_API_TOKEN_CLIENT_SECRET;

// Create an API client
const client = new LightsparkClient(
  new AccountTokenAuthProvider(API_TOKEN_CLIENT_ID, API_TOKEN_CLIENT_SECRET));

This code snippet creates a new LightsparkClient instance, which you'll use to interact with the Lightspark API. The AccountTokenAuthProvider handles authentication using your API credentials.

You need to pass in NODE_PASSWORD to decrypt the Operation Signing Key:

const NODE_ID = process.env.LIGHTSPARK_NODE_ID; 
const NODE_PASSWORD = "1234!@#$"; // In a real scenario, this should be securely stored
client.loadNodeSigningKey(NODE_ID, { password: NODE_PASSWORD, });

With these steps completed, you're now set up to start using Lightspark Connect in your application. In the next sections, we'll explore how to perform operations like funding so you can send payments.

Sending a Lightning Payment

In this section, we'll walk through implementation of sending a payment. Sending a payment on the Lightning network consists of 3 steps:

Funding the node to create outbound channels
Receiving an invoice from your payment recipient
Sending payment for the invoice

Create Funding Address

To fund your node, you need to request a node wallet L1 address to receive funds. Lightspark Connect makes this process super simple. Grab the NODE_ID you saved in the getting credentials section above and pass it in:

const fundingAddress = await client.createNodeWalletAddress(NODE_ID);

Simulate Funding

In Live Mode on MAINNET you'll then create an L1 transaction moving funds to the node wallet. In Test Mode on REGTEST, Lightspark provides APIs to simulate this transaction.

// Simulate funding from L1 to the address created earlier
const fundNodeOutput = await client.fundNode(NODE_ID, 200000);
if (!fundNodeOutput) {
  throw new Error("Unable to fund node");
}
console.log(`Funded amount: ${fundNodeOutput.originalValue}`);

This simple code snippet uses the fundNode method from the Lightspark client to simulate funding your node with 200,000 satoshis (or 0.002 BTC).

Send Payment

In order to make a Lightning payment, the recipient needs to generate and send the sender an invoice. The invoice details important information such as where to send the money and how much money to send. In Test Mode, Lightspark provides APIs to simulate a recipient creating an invoice.

Then the sender pays the invoice from their balance. Here's a code snippet to show you you to send a payment using Lightspark Connect:

// Simulate receiving an invoice
const testInvoice = await client.createTestModeInvoice(
  NODE_ID,
  20_000,
  "example script payment"
);
if (!testInvoice) {
  throw new Error("Unable to create test invoice");
}
console.log(`Invoice created: ${testInvoice}\n`);

// Pay the invoice
const payInvoice = await client.payInvoice(NODE_ID, testInvoice, 1000);
if (!payInvoice) {
  throw new Error("Payment failed");
}
console.log(`Payment done with ID = ${JSON.stringify(payInvoice, null, 2)}\n`);

This code snippet demonstrates how to:

Create a test invoice (simulating receiving an invoice from another party)
Pay the invoice using the payInvoice method The payInvoice method takes three parameters: your node ID, the invoice to pay, and the maximum routing fees for this payment to be sent. We suggest setting maximum routing fees as max(5 sats, 17 bps * transaction amount) in Live Mode.

Next steps

This quickstart guide has walked you through the basics of the Lightning Network and how to get started with Lightspark Connect. We've covered:

Understanding the Lightning Network
Setting up your development environment
Initializing the Lightspark client
Sending a Lightning payment

Take a look at the SDK examples to walk step by step through a sample implementation.