Installing the SDK

Our SDKs are a thin wrapper around the GraphQL API that provides a convenient way to interact with it.

// npm:
$ npm install --save @lightsparkdev/lightspark-sdk
// yarn:
$ yarn add @lightsparkdev/lightspark-sdk

Obtain an API Token (see Authentication) and instantiate a LightsparkClient:

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

const API_TOKEN_CLIENT_ID = <your api token id>;
const API_TOKEN_CLIENT_SECRET = <your api token secret>;

const client = new LightsparkClient(
  new AccountTokenAuthProvider(API_TOKEN_CLIENT_ID, API_TOKEN_CLIENT_SECRET)
);

You are now ready to use the Lightspark SDK!

Browse the documentation and API reference below to see examples of how to use the SDK, or head to our Github Repository for examples.

While we recommend using the built-in functions, it is always possible to use the SDK to execute raw GraphQL requests. The SDK will still take care of the authentication for you:

const conductivity = await client.executeRawRequest({
    queryPayload: `query MyCustomQuery($network) {
  current_account {
    id
    conductivity(bitcoin_networks: [$network])
  }
}`,
    variables: { "network": BitcoinNetwork.MAINNET },
    constructObject: (json) => json["current_account"]["conductivity"]
});

console.log(`My conductivity on MAINNET is ${conductivity}.`)

Querying without an SDK (optional)

Within a single request, you can query as many fields and hop through as many edges as you’d like. The schema is strongly typed so that clients know how to use the full capabilities of the API.

The API provides a number of top level queries (used to fetch data) and mutations (used to create, update, or delete data). Both queries and mutations use the same types that can be returned as a response.

Example of a GraphQL query:

query Test {
  current_account {
    name
    nodes(first: 2) {
      count
      entities {
        id
        conductivity
        channels(first: 2) {
          count
          entities {
            uptime_percentage
          }
        }
        display_name
        local_balance {
          original_value
          original_unit
        }
        status
      }
    }
  }
}

Sample response:

{
  name: "Lightspark Group, Inc.",
  nodes: {
    count: 42,
    entities: [
      {
        id: "bGlnaHRuaW5nX25vZGU6MDE4NTM2ZmU4ZWU1Zjk2YjAwMDA3OTE1YzRkNjExODI=",
        conductivity: 8,
        channels: {
          count: 2,
          entities: [
            { uptime_percentage: 98 },
            { uptime_percentage: 72 },
          ],
        },
        display_name: "Asymptotic Sphinx",
        local_balance: {
          original_value: 42893746,
          original_unit: "SATOSHI",
        },
        status: "READY",
      },
      {
        id: "bGlnaHRuaW5nX25vZGU6MDE4NTM3MDQwNzdjZjk2YjAwMDA4Y2VjM2Y3YTQ1MTM=",
        conductivity: 9,
        channels: {
          count: 8,
          entities: [
            { uptime_percentage: 99 },
            { uptime_percentage: 63 },
          ],
        },
        display_name: "Unsorted Symphony",
        local_balance: {
          original_value: 5353656,
          original_unit: "SATOSHI",
        },
        status: "WALLET_LOCKED",
      },
    ],
  },
}

All requests are sent as a HTTP POST query to the main API endpoint: https://api.lightspark.com/graphql/server/2023-09-13. The HTTP request should have an application/json content-type and its payload should be a JSON object with the following fields:

query: A string that contains the GraphQL "document" for this request. It contains the query or mutation that you want to execute against the Lightspark API.
variables: An optional JSON object whose keys are the query's variable names, and whose values are the values you want to pass to the GraphQL engine.