Overview

LN Markets API (2.0.0)

LN Markets opens a REST and a Websocket API to integrate with your program or trading bot.

This API reference provides information on available endpoints and how to interact with it.

You can find a ready-to-use TypeScript SDK here as well as a Python SDK here.

Signature

LNM-ACCESS-SIGNATURE header is generated by creating a sha256 HMAC using the secret key on the prehash string timestamp + method + path + params (where + represents string concatenation) digested in Base 64.

• method : MUST be UPPER CASE.

• path : is the request path of the URL, e.g.: /v2/user

• timestamp : value is the same as the LNM-ACCESS-TIMESTAMP header.

  It MUST be number of millisecond since Unix Epoch in UTC and it should be within 30 seconds of our API time.

• params : is the request body as a JSON string (with no space, no line return)

  or the request query as URL search params

  and if there is no data it should be an empty string

Here is some example to create the signature

Javascript

const { createHmac } = require('crypto')
const { URLSearchParams } = require('url')

let params = ''

if (method.match(/^(GET|DELETE)$/)) {
  params = new URLSearchParams(data).toString()
} else {
  params = JSON.stringify(data)
}

const signature = createHmac('sha256', secret).update(`${timestamp}${method}${path}${params}`).digest('base64')

Python

import hmac
import base64
import json
import urllib

params = ''

if ((method == 'GET') | (method == 'DELETE')):
    params = urllib.parse.urlencode(data)

elif ((method == 'POST') | (method == 'PUT')):
    params = json.dumps(data, separators=(',', ':'))

signature = base64.b64encode(hmac.new(secret, timestamp + method + path + params, hashlib.sha256).digest())

Bash

signature=$(echo -n "$timestamp$method$path$params" | openssl dgst -sha256 -hmac $SECRET -binary | base64 )

REST API

The API endpoint for mainnet is https://api.lnmarkets.com/v2

If you want to try our API with testnet bitcoin use https://api.testnet.lnmarkets.com/v2

REST Authentication

API key authentication requires each request to be signed (enhanced security measure). You can create and activate new API keys on your profile here. Your API keys should be assigned to access only accounts and permission scopes that are necessary for your app to function.

Making a request

All REST requests must contain the following headers:

Header	Description
LNM-ACCESS-KEY	API key as a string.
LNM-ACCESS-SIGNATURE	Message signature.
LNM-ACCESS-PASSPHRASE	API key passphrase.
LNM-ACCESS-TIMESTAMP	Timestamp for your request.

Request POST and PUT must have content type Content-Type: application/json and be valid JSON and in the body. Request queries with GET and DELETE must not have a body and the header Content-Type: application/json must be omitted.

Websockets API

The websocket endpoint for mainnet is wss://api.lnmarkets.com

If you want to try with testnet bitcoin use wss://api.testnet.lnmarkets.com

This API follows the JSON-RPC specification.

Request sent to the API should be a valid JSON like:

{
  "jsonrpc": "2.0",
  "method": "debug/echo",
  "id": "faffssdfsdf432", // Random id
  "params": {
    "hello": "world"
  }
}

And response would look like:

{
  "jsonrpc": "2.0",
  "id": "faffssdfsdf432", // Same id
  "result": {
    "hello": "world"
  }
}

You need to listen for the id provided in the request to get the response back!

Heartbeats

If you are concerned about your connection silently dropping, we recommend implementing the following flow:

After receiving each message, set a timer duration of 5 seconds. If any message is received before that timer fires, restart the timer. When the timer fires (no messages received in 5 seconds), send a raw ping frame. Expect a raw pong frame in response. If this is not received within 5 seconds, throw an error or reconnect.

Subscription

You can subscribe to different events using the subscribe method. If you wish to unsubscribe, call unsubscribe with the event you want to be unsubscribed from. Here is the full list of available subscriptions.

[
  "futures:btc_usd:index",
  "futures:btc_usd:last-price",
  "options:btc_usd:volatility-index",
  "options:instruments:disable",
  "options:instruments:enable",
  "options:instruments:removed",
]

Limits

We established some limitation across th API to ensure our services integrity.

Futures

There is a maximum of 50 open positions per account.

Options

There is a maximum of 50 open trades per account.

Rate

Requests to our REST API are rate limited to 1 request per second, endpoints which do not require authentication are limited to 30 requests per minute.

Here are Headers related to rate limitation:

Header	Description
Retry-After	Will tell you how many seconds you need to wait to call this endpoint if your limit is down to 0.
X-Ratelimit-Remaining	This is how many request do you have left before blocking.
X-Ratelimit-Reset	This is the timestamp in ms when limitation will be reset.

Requests

If you throw too much error such as 4XX or 5XX, your IP could be banned for a certain period of time.

Errors

Code	Meaning
400	Bad request. Your request is invalid.
401	Unauthorized. Your API key is wrong or you don’t have access to the requested resource.
403	Forbidden. Your API key has the wrong scope.
404	Not found.
405	Method Not Allowed. You tried to access a resource with an invalid method.
418	I’m a teapot.
429	Too many requests. Your connection is being rate limited.
500	Internal server error. Something went wrong, please try again or contact us.
503	Service unavailable. We’re temporarily offline for maintenance. Please try again later.

• OpenAPI version: 3.0.2