Understanding the lemon.markets Trading API

Offering our users the possibility to conveniently trade via an API is what we at lemon.markets have been working on on a daily basis over the past year. As we just started our public beta a few weeks ago, this goal now slowly becomes reality. In this blog post, I want to introduce you to the structure and functionalities of our Trading API so you can easily get started building your own brokerage experience at the stock market. Let’s get going.

Why trade via an API?

The starting point for lemon.markets was in early 2020 when we painfully realised that there’s no brokerage service in Europe that allows its users to build a trading product in a flexible way, just as they imagine it. What initially started as an interface to automate your trades, lemon.markets evolved into an infrastructure that gives you the freedom to build (basically) any kind of product. Some people may be unsatisfied with the current offering of trading apps and want to create their own application. Others may be interested in setting up an automated trading strategy that does all the work for them. Some people might even be interested in placing a trade in their favourite messaging app (what a coincidence, see an example for a Telegram Trading bot here).

So, we set out on bringing this infrastructure to life and (tada 🎉) have now arrived at a point where we want to share what we created with all of you.

You can see the structure of our Trading API below.

Let’s dive into the endpoints

As you can see, there are two base URLs for our Trading API:

https://paper-trading.lemon.markets/v1/

and

https://trading.lemon.markets/v1/

We have separate URLs for Paper and for Real Money Trading. The APIs follow a near-identical structure (with some real-money specifics). This means that before exposing your product to your hard earned money, you can safely deploy it to a simulated paper-money environment. All without making any changes to your implementation. And once you’re happy with it, you can simply exchange the base URL and your project will be running as before, only this time with real money.

For the rest of the article, we will use the Paper Money base URL for demonstration purposes. We will take a look at:

• how to retrieve your account information,
• how to see your spaces and create a new one,
• how to create a new order and see previous orders,
• how to see all your transactions and
• how to monitor your portfolio.

If you are interested in diving deeper into our API: check out our docs. There, you will also find information about how to get access to the API.

Interacting with your account

To retrieve information about your account such as name, email address, the IBAN of your brokerage account or how much cash you have left to invest, make a request against the /account endpoint. See below how to address this endpoint.

import requests

request = requests.get("https://paper-trading.lemon.markets/v1/account/", 
                       headers={"Authorization": "Bearer YOUR-API-KEY-HERE"})
print(request.json())

Spaces

Spaces are an important concept for using the lemon.markets API. It allows you to split your account into different trading projects and thereby limit the overall risk. Find out more about the concept here. To create a new Space, use the following code snippet:

import requests
import json

request = requests.post("https://paper-trading.lemon.markets/v1/spaces/",
          data=json.dumps({
              "name": "MyNewSpace",
              "type": "manual",
              "risk_limit": 10000000,
              "description": "I am trying out my new strategy",
            }), headers={"Authorization": "Bearer YOUR-API-KEY-HERE"})
print(request.json())

Make sure to post the request body in JSON format. You have the option to set a name, type of Space (manual or auto), risk limit (the overall limit you can spend on orders with that trade) as well as a description. To learn more about Spaces, e.g. what the difference between a manual and an automated space is, check out our documentation.

Afterwards, you can see all your Spaces. You can also use the query parameter type to only see manual or auto Spaces. Use the following code snippet for that:

import requests

request = requests.get("https://paper-trading.lemon.markets/v1/spaces/?type=manual", 
                       headers={"Authorization": "Bearer YOUR-API-KEY-HERE"})
print(request.json())

Your response will look something like this. As you can see, you can, among others, retrieve your Space ID, which you can use to perform requests for your space, e.g. placing an order or retrieving your portfolio. You also get information on how much money you have left to spend within that space and what your risk limit is.

{
  "time": "2021-12-20T12:54:09.192+00:00",
  "status": "ok",
  "mode": "paper",
  "result": 
  [
    {
      "name": "MyPersonalSpace",
      "description": "In this Space, I only trade stocks",
      "type": "manual",
      "risk_limit": 100000000,
      "linked": "string",
      "id": "sp_pyJHBffGGDyV4m8rxtJ7BnfGwKLNk3bnBy",
      "buying_power": 97035000,
      "earnings": 0,
      "backfire": 2965000
    }
  ]
}

Orders

Placing orders is one of the core features of the Trading API. You can do that with one simple request. In there, you specify all things relevant for your order placement. Using the “isin” request parameter, we buy one share of Coinbase in the example below. Additionally, you can specify when you want the order to expire (“expires_at”) or the Space you want to place the order within (“space_id”).

import requests
import json

request = requests.post("https://paper-trading.lemon.markets/v1/orders/",
          data=json.dumps({
              "isin": "US19260Q1076",
              "expires_at": "2021-11-10T22:59:00.000+00:00",
              "side": "buy",
              "quantity": 1,
              "venue": "XMUN",
              "space_id": "123456789",
              "notes": "This is an informative note attached to my order"
            }), headers={"Authorization": "Bearer YOUR-API-KEY-HERE"})
print(request.json())

Afterwards, you may want to check the orders you already placed. You can filter the orders returned by the API by different query parameters. For example, you could be interested in only seeing buy orders for a specific ISIN. To retrieve these orders, use:

import requests

request = requests.get("https://paper-trading.lemon.markets/v1/orders/?side=buy&&isin=US88160R1014", 
                       headers={"Authorization": "Bearer YOUR-API-KEY-HERE"})
print(request.json())

Portfolio

Finally, using our Trading API you can also retrieve all of your portfolio items by calling the /portfolio endpoint. To make the request more specific, you can query by space and/or ISIN:

import requests

request = requests.get("https://paper-trading.lemon.markets/v1/portfolio/?space_id=123456789&&isin=US88160R1014/", 
                       headers={"Authorization": "Bearer YOUR-API-KEY-HERE"})
print(request.json())

Conclusion

Alright, that was our little deep dive into the lemon.markets Trading API. We hope you learned something and are now more than hyped to start building. We can’t wait to have you on board. Side note: the Trading API is only one of the two APIs that we offer, the other one is our Market Data API, which you can learn more about here.

We are looking forward to seeing what you are building with us. Make sure to sign up on lemon.markets and build your own brokerage experience at the stock market 🍋