README.md

LN Markets JS API

@lnmarkets/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 @lnmarkets/api

  $> pnpm install @lnmarkets/api

  $> yarn add @lnmarkets/api

Then go to on your LN Markets account under the API section of the Profile to generate an API Token with the right scopes and the right expiry to fit your needs. You'll need to copy this token as it is needed to authenticate yourself and make requests to the lnm.

Websocket API

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.

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

Subscription

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

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('@lnmarkets/api')
  const lnm = new LNMarketsRest({ token: '<YOUR-TOKEN>' })
  const info = await lnm.nodeState()

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.

Options

This HTTP api require an object as parameter. Here is the list of its possible properties.

token:
  type: String
  required: true

network:
  type: String
  required: false
  default: 'mainnet'

version:
  type: String
  required: false
  default: 'v1'

Examples

You can find examples for rest api 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

Methods

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

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 /state/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.

apiState

Retrieve informations related to LN Markets lnm.

# No parameters

Example:

  await lnm.apiState()

GET /state documentation for more details.

nodeState

Show informations about LN Markets lightning node.

# No parameters

Example:

  await lnm.nodeState()

GET /state/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']

endpoint:
  type: String
  required: true

params:
  type: Object
  required: false

credentials:
  type: Boolean
  required: false
  default: false

endpoint is which route you want to communicate with, credentials is your generated token.

Example:

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

Examples

You can find some code examples in the examples folder !