LN Markets JS API

@ln-markets/api is a simple way to connect your Node JS application to LN Markets !

Note: This module does not work in the browser.

Install

You can install this package with npm or yarn:

  $> npm install @ln-markets/api

  $> pnpm install @ln-markets/api

  $> yarn add @ln-markets/api

Then go to on your LN Markets account under the API section of the Profile to generate an API Key with the right permissions to fit your needs.

Usage

You can import either Websocket or Rest class from @ln-markets/api

  const { LNMarketsWebsocket, LNMarketsRest } = require('@ln-markets/api')

  const websocket = new LNMarketsWebsocket()
  const rest = new LNMarketsRest()

Authentication

For authentication you need your api key secret and passphrase

Without you will not bet able to authenticate

⚠️ Never share your API Key, Secret or Passphrase

Key

• As a js variable

  const key = `<LNM API KEY>`
  const { LNMarketsWebsocket } = require('@ln-markets/api')
  const lnm = new LNMarketsWebsocket({ key })

• Pass LNMARKETS_API_KEY env var to your app

  // process.env.LNMARKETS_API_KEY = `<LNM API KEY>`
  const { LNMarketsWebsocket } = require('@ln-markets/api')
  const lnm = new LNMarketsWebsocket()

Secret

• As a js variable

  const secret = `<LNM API SECRET>`
  const { LNMarketsWebsocket } = require('@ln-markets/api')
  const lnm = new LNMarketsWebsocket({ secret })

• Pass LNMARKETS_API_SECRET env var to your app

  // process.env.LNMARKETS_API_SECRET = `<LNM API SECRET>`
  const { LNMarketsWebsocket } = require('@ln-markets/api')
  const lnm = new LNMarketsWebsocket()

Passphrase

• As a js variable

  const passphrase = `<LNM API PASSPHRASE>`
  const { LNMarketsWebsocket } = require('@ln-markets/api')
  const lnm = new LNMarketsWebsocket({ passphrase })

• Pass LNMARKETS_API_PASSPHRASE env var to your app

  // process.env.LNMARKETS_API_PASSPHRASE = `<LNM API PASSPHRASE>`
  const { LNMarketsWebsocket } = require('@ln-markets/api')
  const lnm = new LNMarketsWebsocket()

Configuration

You can pass the network and version in the constructor or specify it with environement variable.

By default the package will connect to the mainnet api.

Network

• Testnet with constructor params

  const { LNMarketsWebsocket } = require('@ln-markets/api')
  const lnm = new LNMarketsWebsocket({ network: 'testnet' })

• Pass LNMARKETS_API_NETWORK env var to your app

  // process.env.LNMARKETS_API_NETWORK = 'testnet'
  const { LNMarketsWebsocket } = require('@ln-markets/api')
  const lnm = new LNMarketsWebsocket()

LNMARKETS_API_VERSION There is only one version aka v1

LNMARKETS_API_HOSTNAME is only used for debug

Websocket API

⚠️ Websocket API only support subscription

Websockt API is limited now for bid offer and index update, we will make a dedicated Websocket api soon !

The message format is using JSON-RPC spec.

The websocket class has an auto ping-pong mechanism and reconnect

  const { LNMarketsWebsocket } = require('@ln-markets/api')
  const lnm = new LNMarketsWebsocket()
  lnm.on('message', console.log)
  await lnm.connect()

The LNMarketsWebsocket class emit events on connected message error

Subscription

You can subscribe to LNM Markets public event such as futures bid offer, index and options data.

Authentication

You need to call the authenticate method

Examples

You can find examples for websocket here

REST API

All you have to do now is to instanciate a LNMarketsRest object this way:

  const { LNMarketsRest } = require('@ln-markets/api')
  const lnm = new LNMarketsRest()
  const info = await lnm.appNode()

After this, you'll be able to use all the documented API methods below.

All these functions are wrappers for documented public endpoints from LN Markets API v1. See specification here.

Be careful, all methods expect an object as parameter with the correct parameters in it.

Examples

You can find examples for rest here

Generic Methods

These methods are designed to fill the gaps if the API evolves and the future but this package isn't up to date.

• requestAPI
• beforeRequestApi

Methods

• futuresGetTicker
• futuresNewPosition
• futuresGetPositions
• futuresUpdatePosition
• futuresAddMarginPosition
• futuresCancelAllPositions
• futuresCancelPosition
• futuresCashinPosition
• futuresCloseAllPosisitions
• futuresClosePosition
• futuresIndexHistory
• futuresBidOfferHistory
• futuresFixingHistory
• futuresCarryFeesHistory
• deposit
• depositHistory
• futuresHistory
• getAnnouncements
• getLeaderboard
• getUser
• appConfiguration
• appNode
• updateUser
• withdraw
• withdrawHistory

futuresGetTicker

Get the ticker of LN Markets

Example:

  await lnm.futuresGetTicker()

GET /futures/ticker documentation for more details.

futuresNewPosition

Open a new position on the market.

type:
  type: String
  required: true
  enum: ['l', 'm']

side:
  type: String
  required: true
  enum: ['b', 's']

margin:
  type: Integer
  required: false

leverage:
  type: Float
  required: true

quantity:
  type: Integer
  required: false

takeprofit:
  type: Integer
  required: false

stoploss:
  type: Integer
  required: false

price:
  type: Float
  required: false

Example:

  await lnm.futuresNewPosition({
    type: 'm',
    side: 's',
    margin: 10000,
    leverage: 25.5,
  })

POST /futures documentation for more details.

futuresGetPositions

Retrieve all or a part of user positions.

type:
  type: String
  required: true
  enum: ['open', 'running', 'closed']
  default: 'open'

from:
  type: Integer
  required: false

to:
  type: Integer
  required: false

limit:
  type: Integer
  required: false
  default: 100

Example:

  await lnm.futuresGetPositions({
    type: 'running'
  })

GET /futures documentation for more details.

futuresUpdatePosition

Modify stoploss or takeprofit parameter of an existing position.

pid:
  type: String
  required: true

type:
  type: String
  required: true
  enum: ['takeprofit', 'stoploss']

value:
  type: Float
  required: true

Example:

  await lnm.futuresUpdatePosition({
    pid: 'b87eef8a-52ab-2fea-1adc-c41fba870b0f',
    type: 'stoploss',
    value: 13290.5
  })

PUT /futures documentation for more details.

addMargin

Add more margin to an existing position.

amount:
  type: Integer
  required: true
pid:
  type: String
  required: true

Example:

  await lnm.addMargin({
    amount: 20000,
    pid: '249dc818-f8a5-4713-a3a3-8fe85f2e8969'
  })

POST /futures/add-margin documentation for more details.

futuresCancelAllPositions

Cancel all oponed (not running) positions for this user.

# No parameters

Example:

  await lnm.futuresCancelAllPositions()

DELETE /futures/all/cancel documentation for more details.

futuresCancelPosition

Cancel a particular position for this user.

pid:
  type: String
  required: true

Example:

  await lnm.futuresCancelPosition({
    pid: 'b87eef8a-52ab-2fea-1adc-c41fba870b0f'
  })

POST /futures/cancel documentation for more details.

futuresCashinPosition

Retrieve a part of the general PL of a running position.

amount:
  type: Integer
  required: true
pid:
  type: String
  required: true

Example:

  await lnm.futuresCashinPosition({
    amount: 1000,
    pid: "99c470e1-2e03-4486-a37f-1255e08178b1"
  })

POST /futures/cash-in documentation for more details.

futuresCloseAllPosisitions

Close all running position for this user.

# No parameters

Example:

  await lnm.futuresCloseAllPosisitions()

DELETE /futures/all/close documentation for more details.

futuresClosePosition

Close a particular running position for this user.

pid:
  type: String
  required: true

Example:

  await lnm.futuresClosePosition({
    pid: 'a2ca6172-1078-463d-ae3f-8733f36a9b0e'
  })

DELETE /futures documentation for more details.

futuresIndexHistory

Get index history data.

from:
  type: Integer
  required: false

to:
  type: Integer
  required: false

limit:
  type: Integer
  required: false
  default: 100

Example:

  await lnm.futuresIndexHistory({
    limit: 20
  })

GET /futures/history/index documentation for more details.

futuresBidOfferHistory

Get bid and offer data over time.

from:
  type: Integer
  required: false

to:
  type: Integer
  required: false

limit: Integer
  required: false
  default: 100

Example:

  await lnm.futuresBidOfferHistory({
    limit: 20
  })

GET /futures/history/bid-offer documentation for more details.

futuresFixingHistory

Get fixing data history.

from:
  type: Integer
  required: false

to:
  type: Integer
  required: false

limit:
  type: Integer
  required: false
  default: 100

Example:

  await lnm.futuresFixingHistory({
    limit: 20
  })

GET /futures/history/fixing documentation for more details.

futuresCarryFeesHistory

Get carry-fees history.

from:
  type: Integer
  required: false

to:
  type: Integer
  required: false

limit:
  type: Integer
  required: false
  default: 100

Example:

  await lnm.futuresCarryFeesHistory({
    limit: 20
  })

GET /futures/carry-fees documentation for more details.

deposit

Add funds to your LN Markets balance.

amount:
  type: Integer
  required: true
unit:
  type: String
  required: false
  default: 'sat'

Example:

  await lnm.deposit({
    amount: 25000
  })

POST /user/deposit documentation for more details.

depositHistory

Retrieve deposit history for this user.

from:
  type: Integer
  required: false

to:
  type: Integer
  required: false

limit:
  type: Integer
  required: false

Example:

  await lnm.depositHistory({
    limit: 30
  })

GET /user/deposit documentation for more details.

getAnnouncements

Retrieve announcements made by LN Markets.

# No parameters

Example:

  await lnm.getAnnouncements()

GET /app/announcemenets documentation for more details.

getLeaderboard

Queries the 10 users with the biggest positive PL.

# No parameters

Example:

  await lnm.getLeaderboard()

GET /futures/leaderboard documentation for more details.

getUser

Retrieve user informations.

# No parameters

Example:

  await lnm.getUser()

GET /user documentation for more details.

appConfiguration

Retrieve informations related to LN Markets.

# No parameters

Example:

  await lnm.appConfiguration()

GET /app/configuration documentation for more details.

appNode

Show informations about LN Markets lightning node.

# No parameters

Example:

  await lnm.appNode()

GET /app/node documentation for more details.

updateUser

Modify user account parameters.

show_leaderboard:
  type: Boolean
  required: false

show_username:
  type: Boolean
  required: false

username:
  type: String
  required: false

email:
  type: String
  required: false

resend_email:
  type: Boolean
  required: false

Example:

  await lnm.updateUser({
    show_username: true,
    show_leaderboard: true,
    username: 'API-Connector',
  })

PUT /user documentation for more details.

withdraw

Move funds from LN Markets to your wallet via BOLT11 invoice.

amount:
  type: Integer
  required: true

unit:
  type: String
  required: false
  default: 'sat'

invoice:
  type: String
  required: true

Example:

  await lnm.withdraw({
    amount: 1000,
    invoice: 'lntb100u1p0jr0ykpp5ldx3un8ym6z0uwjxd083mp2rcr04d2dv0fkx729ajs62pq9pfjqqdql23jhxapdwa5hg6rywfshwttjda6hgegcqzpgxq92fjuqsp5m6q0fzynu2qr624mzjc285duurhccmkfg94mcdctc0p9s7qkrq8q9qy9qsqp862cjznpey5r76e7amhlpmhwn2c7xvke59srhv0xf75m4ksjm4hzn8y9xy0zs5ec6gxmsr8gj4q23w8ped32llscjcneyjz2afeapqpu4gamz'
  })

POST /user/withdraw documentation for more details.

withdrawHistory

Retrieve user withdraw history.

from:
  type: Integer
  required: false

to:
  type: Integer
  required: false

limit:
  type: Integer
  required: false

Example:

  await lnm.withdrawHistory({
    limit: 25
  })

GET /user/withdraw documentation for more details.

requestAPI

This method is used in case where no wrapper is (yet) available for a particular endpoint.

method:
  type: String
  required: true
  enum: ['GET', 'PUT', 'POST', 'DELETE']

path:
  type: String
  required: true

params:
  type: Object
  required: false

credentials:
  type: Boolean
  required: false
  default: false

Example:

  await lnm.requestAPI({
    method: 'GET',
    path: '/user',
    credentials: true
  })