App Development

Build a lightning application using Core Lightning APIs.

Interacting with CLN Node

There are several ways to connect and interact with a Core Lightning node in order to build a lightning app or integrate lightning in your application.

  • Using JSON-RPC commands if you're building an application in the same system as the CLN node.
  • Using REST APIs if you're building an application in a remote client and want to connect to the CLN node over a secure network using REST interface.
  • Using gRPC APIs if you're building an application in a remote client and want to connect to the CLN node over a secure network using gRPC interface.
  • Using Commando Plugin to connect to a CLN node over the lightning network and issue commands.
  • Using WSS Proxy to connect to a CLN node over web secure socket proxy.
  • Third-party libraries that offer JSON over HTTPS or GraphQL (deprecated) frameworks to connect to a CLN node remotely.

CLN connection URIs

This section outlines the standard URI formats for connecting to Core Lightning (CLN) nodes via different protocols.

Commando WebSocket Connection

commando+<protocol>://<cln-host>:<ws-port>?pubkey=<pubkey>&rune=<rune>&invoiceRune=<invoice-rune>&certs=<combined-base64-encoded-clientkey-clientcert-cacert>

Parameters:

  • protocol: ws or wss (WebSocket or secure WebSocket)
  • cln-host: Hostname or IP address of the CLN node
  • ws-port: WebSocket port
  • pubkey: Node's public key (hex encoded)
  • rune: Authentication rune for general commands
  • invoiceRune: Specific rune for invoice creation (optional)
  • certs: Base64-encoded concatenation of client key, client cert, and CA cert

Example:

commando+wss://cln.local:5001?pubkey=023456789abcdef&rune=8hJ6ZKFvRune&invoiceRune=5kJ3ZKFvInvRune&certs=LS0tLS1CRUdJTiBQUklWQVRFIEtFWS0t

REST API Connection

clnrest+<protocol>://<rest-host>:<rest-port>?rune=<rune>&certs=<combined-base64-encoded-clientkey-clientcert-cacert>

Parameters:

  • protocol: http or https
  • rest-host: Hostname or IP address of the REST interface
  • rest-port: REST API port (typically 3010)
  • rune: Authentication rune for REST API access
  • certs: Base64-encoded concatenation of client key, client cert, and CA cert

Example:

clnrest+https://cln.local:3010?rune=8hJ6ZKFvRune&certs=LS0tLS1CRUdJTiBQUklWQVRFIEtFWS0t

gRPC Connection

clngrpc://<grpc-host>:<grpc-port>?pubkey=<pubkey>&protoPath=<path-to-proto>&certs=<combined-base64-encoded-clientkey-clientcert-cacert>

Parameters:

Example:

clngrpc://cln.grpc:9736?pubkey=023456789abcdef&protoPath=/path/to/cln.proto&certs=LS0tLS1CRUdJTiBQUklWQVRFIEtFWS0t

Image of available API interfaces and transport protocols

A visual chart of all interface and transport protocols to interact with a CLN node.

A visual chart of available API interfaces and transport protocols for interacting with a CLN node


Core Lightning (previously c-lightning) is a lightweight, highly customizable and standard compliant implementation of the Lightning Network protocol.

© 2023 Core Lightning
All rights reserved.

Discussion Forum

The official Core Lightning forum is hosted at discuss.corelightning.org

BuildonL2 Community

The official BuildOnL2 community lives at community.corelightning.org. Join us and build the future of bitcoin on lightning.

Mailing List

For general discussions about CLN implementation, use [email protected]. For the Lightning Network, use [email protected]

Telegram

Community-driven telegram group where most of the node operators hang out. Go to https://t.me/lightningd to join.

Discord

Community-driven discord server where the devs flock together. Go to https://discord.gg/w27fMFESMN to join.

Internet Relay Chat

Don't hesitate to reach out to us on IRC at #lightning-dev @ libera.chat, #c-lightning @ libera.chat.