Documentation Portal

REST APIs

Suggest Edits

CLNRest

CLNRest is a lightweight Python-based built-in Core Lightning plugin (from v23.08) that transforms RPC calls into a REST service.
It also broadcasts Core Lightning notifications to listeners connected to its websocket server. By generating REST API endpoints,
it enables the execution of Core Lightning's RPC methods behind the scenes and provides responses in JSON format.

An online demo for the REST interface is available at REST API REFERENCE.

📘

Pro-tip

REST API REFERENCE can also be tested with your own server.

By default, the base URL is set to connect with the Blockstream-hosted regtest node.

However, it can be configured to connect to your own cln node as described below:

  • Select {protocol}://{ip}:{port}/ from Base URL dropdown on the right section of the page.

  • Click on the right side of the dropdown and configure protocol, ip and port values according to your setup.

  • The ip should be configured with your system's public IP address.

  • Default clnrest-host is 127.0.0.1 but this testing will require it to be 0.0.0.0.

Note: This setup is for testing only. It is highly recommended to test with non-mainnet (regtest/testnet) setup only.

Installation

The plugin is built-in with Core Lightning but its python dependencies are not, and must be installed separately.
Install required packages with pip install -r plugins/clnrest/requirements.txt.

Note: if you have the older c-lightning-REST plugin, you can configure Core Lightning with disable-plugin=clnrest.py
option to avoid confusion with this one. You can also run both plugins simultaneously till all your applications
are not migrated to clnrest.

Configuration

If clnrest-port is not specified, the plugin will disable itself.

  • --clnrest-port: Sets the REST server port to listen to (3010 is common)

  • --clnrest-protocol: Specifies the REST server protocol. Default is HTTPS.

  • --clnrest-host: Defines the REST server host. Default is 127.0.0.1.

  • --clnrest-certs: Defines the path for HTTPS cert & key. Default path is same as RPC file path to utilize gRPC's client certificate.
    If it is missing at the configured location, new identity will be generated.

  • --clnrest-csp: Creates a whitelist of trusted content sources that can run on a webpage and helps mitigate the risk of attacks.
    Default CSP:
    default-src 'self'; font-src 'self'; img-src 'self' data:; frame-src 'self'; style-src 'self' 'unsafe-inline'; script-src 'self' 'unsafe-inline';
    Example CSP:
    clnrest-csp=default-src 'self'; font-src 'self'; img-src 'self'; frame-src 'self'; style-src 'self'; script-src 'self';.

  • --clnrest-cors-origins: Define multiple origins which are allowed to share resources on web pages to a domain different from the
    one that served the web page. Default is * which allows all origins. Example to define multiple origins:

clnrest-cors-origins=https://localhost:5500
clnrest-cors-origins=http://192.168.1.50:3030
clnrest-cors-origins=https?://127.0.0.1:([0-9]{1,4}|[1-5][0-9]{4}|6[0-4][0-9]{3}|65[0-4][0-9]{2}|655[0-2][0-9]|6553[0-5])
  • --clnrest-swagger-root: Root url for Swagger UI. Default is /. Example: clnrest-swagger-root=/doc

Server

With the default configurations, the Swagger user interface will be available at https://127.0.0.1:3010/.
The POST method requires rune header for authorization.

  • A new rune can be created via createrune or the list of
    existing runes can be retrieved with showrunes command.

Note: in version v23.08, a parameter Nodeid was required to be the id of the node we're talking to (see id (pubkey) received
from getinfo). You can still send this for backwards compatibility,
but it is completely ignored.

cURL

Example curl command for POST will also require a rune header like below:
curl -k -X POST 'https://localhost:3010/v1/getinfo' -H 'Rune: <node-rune>'

With -k or --insecure option curl proceeds with the connection even if the SSL certificate cannot be verified.
This option should be used only when testing with self signed certificate.

Websocket Server

Websocket server is available at https://127.0.0.1:3010. clnrest queues up notifications received for a second
then broadcasts them to all listeners.

This websocket server requires a rune with at least readonly access for authorization. The default method used
for current validation is listclnrest-notifications. User can either provided a rune with minimum readonly
access or can create a new special purpose rune, only for websocket validation, with restrictions='[["method=listclnrest-notifications"]]'.
The client will only receive notifications if rune, provided in headers, allows it.

Websocket client examples

Python

import socketio
import requests

http_session = requests.Session()
http_session.verify = True
http_session.headers.update({
    "rune": "your-generated-rune"
})
sio = socketio.Client(http_session=http_session)

@sio.event
def connect():
    print("Client Connected")

@sio.event
def disconnect():
    print(f"Server connection closed.\nCheck CLN logs for errors if unexpected")

@sio.event
def message(data):
    print(f"Message from server: {data}")

@sio.event
def error(err):
    print(f"Error from server: {err}")

sio.connect('http://127.0.0.1:3010')

sio.wait()

NodeJS

const io = require('socket.io-client');

const socket = io.connect('http://127.0.0.1:3010', {extraHeaders: {rune: "your-generated-rune"}});

socket.on('connect', function() {
  console.log('Client Connected');
});

socket.on('disconnect', function(reason) {
  console.log('Server connection closed: ', reason, '\nCheck CLN logs for errors if unexpected');
});

socket.on('message', function(data) {
  console.log('Message from server: ', data);
});

socket.on('error', function(err) {
  console.error('Error from server: ', err);
});

HTML

<!DOCTYPE html>
<html>
<head>
    <title>Socket.IO Client Example</title>
    <script src="https://cdn.socket.io/4.0.1/socket.io.min.js"></script>
</head>
<body>
    <h1>Socket.IO Client Example</h1>
    <hr>
    <h3>Status:</h3>
    <div id="status">Not connected</div>
    <hr>
    <h3>Send Message:</h3>
    <input type="text" id="messageInput" placeholder="Type your message here">
    <button onclick="sendMessage()">Send</button>
    <hr>
    <h3>Received Messages:</h3>
    <div id="messages"></div>
    <script>
        const statusElement = document.getElementById('status');
        const messagesElement = document.getElementById('messages');

        const socket = io('http://127.0.0.1:3010', {extraHeaders: {rune: "your-generated-rune"}});

        socket.on('connect', () => {
            statusElement.textContent = 'Client Connected';
        });

        socket.on('disconnect', (reason) => {
            statusElement.textContent = 'Server connection closed: ' + reason + '\n Check CLN logs for errors if unexpected';
        });

        socket.on('message', (data) => {
            const item = document.createElement('li');
            item.textContent = JSON.stringify(data);
            messagesElement.appendChild(item);
            console.log('Message from server: ', data);
        });

        socket.on('error', (err) => {
            const item = document.createElement('li');
            item.textContent = JSON.stringify(err);
            messagesElement.appendChild(item);
            console.error('Error from server: ', err);
        });

        function sendMessage() {
            const message = messageInput.value;
            if (message) {
                socket.emit('message', message);
                messageInput.value = '';
            }
        }
    </script>
</body>
</html>

Updated 3 days ago