#👋 Introduction

You want to start right away:

• generate snapshots
• calulate snapshot differences
• or just analyze particular channels or nodes BUT dont have any gossip data?

No problem! 😁

I provide the necessary infrastructure for that. To limit access you need to have an ApiKey. Please fill out the form below and I will give you an ApiKey for free. I am interested in your research, feel free to give some context of your research.

Using an ApiKey based authentication is a temporary solution and has the advantage that the server does not get shot down easily. Additionally you do not have to register with your data.

#Request an ApiKey

Please enter a valid Email address that you can access. I will respond on that address with the ApiKey as quick as possible.

#Setup

#Prerequisits

You need to have Python 3 installed on your machine. Verify if the following command yields to the same result

Note that the library should work for every python 3.x version. It has been extensivly tested for python 3.13, which I recommend.

#Environment

I highly recommend using virtual environments to manage dependencies. You will need the ln-history-python-client library, so you can easily parse the gossip messages which will be returned as raw bytes into something more readable, e. g. JSON format.

We first create the virtual environment .venv. We assume that you have python installed on your system

Next we activate the virtual environment

You should now see a (.venv) at the front in your shell, something like this

#Install

We install the lnhistoryclient via pip into our virtual environment.

#Use it

Create a python file analysis.py in your project and copy the following code into it:

import os
from datetime import datetime

from lnhistoryclient.Lnhistoryrequster import LnhistoryRequester, LnhistoryRequesterError

# Example usage of the client
api_key = "YOUR_API_KEY"

with LnhistoryRequester(api_key) as client:
    try:
        # Get a snapshot at a specific time and create NetworkX graph
        timestamp = datetime(2021, 2, 6, 1, 0, 0)
        
        # Option 1: Get NetworkX graph directly
        graph = client.get_snapshot_at_timestamp(timestamp, return_graph=True, stopwatch=True)
        print(f"Graph created with {graph.number_of_nodes()} nodes and {graph.number_of_edges()} edges")

        print("="*50)
        
        # Option 2: Get graph and save to file
        graph = client.get_snapshot_at_timestamp(
            timestamp, 
            return_graph=True,
            save_to_file="lightning_network.graphml",
            format="graphml",
            stopwatch=True
        )
        print("Graph saved to lightning_network.graphml")

        print("="*50)
        
        # Option 3: Get raw file path for manual processing
        file_path = client.get_snapshot_at_timestamp(timestamp, return_graph=False, stopwatch=True)
        print(f"Raw data available at: {file_path}")
        # Don't forget to clean up the temp file when done
        os.unlink(file_path)
        
    except LnhistoryRequesterError as e:
        print(f"API Error: {e}")
    except Exception as e:
        print(f"Unexpected error: {e}")

Run the code from your virtual environment.

The methods of the LnhistoryRequester.py class are very flexibel. You can play around with dfferent settings.

See the Python Client documentation for details.