A series of tutorials to make it easy for non-coders to trade on LN Markets via our API with several programming languages, here with cURL.

Reference Docs

Our API reference provides information on available endpoints and how to interact with it: https://lnmarkets.github.io/docs/

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

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

Get your JSON Web Token

In order to use LN Markets API, you first need to create your authentication token. We are currently using JSON Web Token (JWT).

Go to your Profile (click on the menu in the upper right corner) and select API Tokens. You can now generate your token for various scopes: user, positions, deposit, withdraw. It can be valid for a given period of time or indefinitely.

Here we created a token for all the scopes, without expiry. We copy it for later usage (button copy):

Setup your cURL environment

cURL is a command line tool and library for transferring data with URLs (since 1998).

It is also used in cars, television sets, routers, printers, audio equipment, mobile phones, tablets, settop boxes, media players and is the internet transfer backbone for thousands of software applications affecting billions of humans daily.

Here is how to install curl on Unix, Windows, Mac, iOS and Android: https://curl.se/docs/install.html

In this tutorial we will run a shell file directly in our Terminal.

Enter your API Token

Copy your token in JWT = '...':

#!/bin/bash

JWT = "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiI0MThlNGZlZi1lM2M1LTQ4ZmItODFlOC0yMzc1Yj[...]cDA2bjc5MHdxMzdtcSIsImlhdCI6MTYwNTcyMTIxNX0.D1ifOH1NvIQx0FsbU__Y_vv_Grl-h6ZBgjHexHNY-6M"

Get your positions' history

Change ht = "all", ht = "open", ht = "closed" to get the history of all your position, open positions, and closed positions

# Get your positions' history

ht="open"

curl --request GET \
  --url https://api.lnmarkets.com/positions?type=${ht} \
  --header "accept: application/json" \
  --header "authorization: Bearer ${JWT}"

Here we check for "open" positions, and since none is open at moment we get this empty JSON file:

If we check for "closed" positions, here is a sample of the many positions we have previously closed for this particular account:

Create a position

In order to create a position, we must enter in the constant body its type ('m' for market order, 'l' for limit order), its side ('b' for buy, 's' for sell) and the required parameters. Which are either quantity and leverage (quantity of 1 means 1 contract, each contract is worth 1 USD, leverage must be between 1 and 50) or margin and leverage (max margin is currently limited to 0.01 BTC = 100,000,000 satoshis):

# Create a market order

curl --request POST \
  --url https://api.lnmarkets.com/positions \
  --header "accept: application/json" \
  --header "authorization: Bearer ${JWT}" \
  --header "content-type: application/json" \
  --data '{"type":"m","side":"b", "quantity":1,"leverage":1}'

We run this code to create our new position:

We can also see the position open in our LN Markets account:

Update a position

We can add a take profit and/or stop loss to this position. We just need to enter in the constant body the position id 'pid', the type of update ('takeprofit' or 'stoploss') and its value:

# Update a position

curl --request PUT \
  --url https://api.lnmarkets.com/positions \
  --header "accept: application/json" \
  --header "authorization: Bearer ${JWT}" \
  --header "content-type: application/json" \
  --data '{"pid":"16335e72-edc0-42a6-9197-e8ba60d1b35f","type":"takeprofit","value":40000}'

We get the following output:

And we can check the update for confirmation in our LN Markets account:

Close a position

We can then close this position with our pid:

# Close a position

pid="16335e72-edc0-42a6-9197-e8ba60d1b35f"

curl --request DELETE \
  --url "https://api.lnmarkets.com/positions?pid=${pid}" \
  --header "accept: application/json" \
  --header "authorization: Bearer ${JWT}"

We get the following output:

And we can check that the position was closed in our LN Markets account:

Cancel a position

Only limit orders that have not yet been filled can be canceled. First, let's create a limit buy order at Price 30,000$ for a Quantity of 1 contract and Leverage of 1:

# Create a limit order

curl --request POST \
  --url https://api.lnmarkets.com/positions \
  --header "accept: application/json" \
  --header "authorization: Bearer ${JWT}" \
  --header "content-type: application/json" \
  --data '{"type":"l","side":"b", "price": 30000, "quantity":1,"leverage":1}'

The limit order is now open:

As long as the order has not been filled, we can cancel it using its pid:

# Cancel a position

curl --request POST \
  --url https://api.lnmarkets.com/positions/cancel \
  --header "accept: application/json" \
  --header "authorization: Bearer ${JWT}" \
  --header 'content-type: application/json' \
  --data '{"pid":"1861f8ca-6c85-4294-8750-25352d4ad45d"}'

The position is now cancelled:

We can verify that in our closed positions blotter:

Deposit funds to your account

In order to generate a Lightning Network invoice to fund your account on LN Markets, enter the desired amount (between 1,000 and 1 million sats) and unit ('sat' or 'btc') in body:

# Deposit

curl --request POST \
  --url https://api.lnmarkets.com/user/deposit \
  --header "accept: application/json" \
  --header "authorization: Bearer ${JWT}" \
  --header 'content-type: application/json' \
  --data '{"amount":1000,"unit":"sat"}'

And you get the invoice, that you need to pay within 45 seconds for your deposit to be successful:

Withdraw funds from your account

You can either withdraw funds via an invoice or via lnurl-withdraw (here is the list of wallets that support it). In order to withdraw via an invoice you enter in the payload the amount, the unit, and your invoice:

# Withdraw via Invoice

  curl --request POST \
  --url https://api.lnmarkets.com/user/withdraw \
  --header "accept: application/json" \
  --header "authorization: Bearer ${JWT}" \
  --header 'content-type: application/json' \
  --data '{"amount":1000,"unit":"sat","invoice":"lnbc10u1psqw925pp5s0l7cs5e2gansyxr04d95sh4c6sgmfp55cu9cyted2sza2t7lsesdqqxqyjw5q9qtzqqqqqq9qsqsp5zgxxunpef4na6kwgdmvvu7lwzp9jxv8uqct8a4f2eu49ruwefpjsrzjqwryaup9lh50kkranzgcdnn2fgvx390wgj5jd07rwr3vxeje0glclluye5e2a70hyqqqqqlgqqqqqeqqjquuqydl6vf3g9mmhwftv85pera3mmdr2e8fqya5vt44v69ad2jda3c4fyax58e4atpr22n9skatz40w2u3wctcj0zcpxgwf23q72g57qqke4utk"}'

And you get the instant withdrawal confirmation:

{"amount":1000,"paymentsecret":"4e789efcbba7807ceb09886cefa5ec7b544ef8343ef105ea7c48dc017d4d36a1","wid":"0c78f631-a742-467c-ade5-12373f3aded4","paymenthash":"8e3csdf74e014713b5c97916bcd558fa7c031fe362c515ca7aa4b363a4465a04"}

Get the Leaderboard

Now it is time for you to check if you made it to the Leaderboard!

# Get current Leaderboard

curl --request GET \
  --url https://api.lnmarkets.com/state/leaderboard \
  --header 'accept: application/json'

By default, you do not appear in the leaderboard. It's only if you authorize it your profile section that you may appear under your desired pseudonymous. Here is the Top 10:

Create an account

You can either create an account using credentials or with lnurl-auth. Here we show how do it via credentials.

First, you need to request new credentials:

#Request new credentials

curl --request GET \
  --url https://api.lnmarkets.com/login/credentials \
  --header 'accept: application/json'

And you get the 100 sats invoice you need to pay within 90 seconds to create new credentials:

After paying the invoice, we enter in the payload the payment hash of the invoice and the login and password we want to use:

# Register new credentials

curl --request PUT \
  --url https://api.lnmarkets.com/login/credentials \
  --header 'accept: application/json' \
  --header 'content-type: application/json' \
  --data '{"login":"curl_tuto","password":"mYUNh4x0r48L3P422w0rd","paymentHash":"3f4beaeb38f1f843bc3e6d3c63ac3ea42f919893e35469ccea3256a805e20d89"}'

Our account is now created:

There is much more

There are plenty of other actions that we did not cover in this tutorial (account creation and withdraw via lnurl, API tokens revocation, state of LN Markets node and our API, announcements, etc.), but that you will be able to run easily using the previous lines of codes.

Should you have any questions about using the API, feel free to join LN Markets Telegram support group: https://www.t.me/lnmarkets