Working with lemon.markets Spaces👩‍🚀

Hey there, it’s Joanne from lemon.markets. We are building a brokerage API to enable developers to build their own brokerage experience at the stock market. In this blog post, we’re not just hopping on the trendy #ToTheMoon hashtag, but instead introduce a real lemon.markets concept: the Space 🚀. Spaces are a crucial component for using lemon.markets. We’ve already written a whole article about the concept and why you should use them, but if you’d like the TL;DR: a Space is an isolated workspace for you to run your trading algorithm/product in such that you can segment your different projects.

In this article, I’ll walk you through how to work with the /spaces endpoint (note that all examples will be in Python). Strap in, we’re blasting off in 3.. 2.. 1.. 👾

Getting your Space(s) 🌌

When you sign-up to lemon.markets, we’ll automatically create a ‘Default’ Space for you — meaning you can start trading right away. Let’s look at that Space, shall we? To retrieve a list of your Spaces, send the following request:

import requests

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

print(request.json())

We are using the Paper Trading URL in these examples, but you can apply the same concepts to the Real Money environment by changing the URL to https://trading.lemon.markets/v1/spaces/

This will output something along the lines of:

{
    "time": "2021-12-09T14:14:27",
    "status": "ok",
    "results": [
        {
            "name": "Default",
            "description": null,
            "type": "manual",
            "risk_limit": 100000000,
            "linked": null,
            "created_at": "2021-11-11T19:04:03.984+00:00",
            "id": "sp_example",
            "buying_power": 100000000,
            "earnings": 0,
            "backfire": 0
        },
    ],
    "previous": null,
    "next": null,
    "total": 1,
    "page": 1,
    "pages": 1
}

Each Space has an associated ID. We’ve changed the “id” to “sp_example” in this response for the sake of the article, but you’ll get a longer string.

At this point, we only have a single Space, which is why this list only contains a single element (can also be seen from the total parameter in the response). Each Space can be identified by its Space ID (id in the response). If you want to retrieve the details for a single Space, you can specify the Space ID as a path parameter. This means the URL in the above request changes to:

https://paper-trading.lemon.markets/v1/spaces/{space_id}/

where space_id is the ID of the desired Space.

It’s also possible to filter the retrieved list of Spaces by type (automatic or manual) by including the query parameter type in the URL. For example:

https://paper-trading.lemon.markets/v1/spaces/?type=manual

So, what does this response tell you? You can access the name of the Space and it’s description (which is null in this case, but I’ll show you how to add a description to a new Space shortly). You can also see whether it’s a ‘manual’ or ‘automatic’ Space, namely whether your Space is configured with order execution that requires manual approval or not. You can see the risk limit, the amount of funds that you have allocated to that Space (note: monetary amounts are represented with 4 trailing zeroes, i.e. €100 is represented as 1000000). You’ll see whether it is linked to a Real Money/Paper Space, when it was created and its ID. And lastly, you’ll be able to retrieve the buying power, which is the amount of money you have left to invest, your earnings, which is the profit of that Space and your backfire, which are your aggregated earnings and losses.

Creating a Space 🛸

To create a new Space, send the following POST request:

import requests
import json

request = requests.post("https://paper-trading.lemon.markets/v1/spaces/",
          data=json.dumps({
              "name": "My Space",
              "type": "manual",
              "risk_limit": 10000000,
              "description": "I want to buy ETFs with this Space",
            }), headers={"Authorization": "Bearer YOUR-API-KEY"})

print(request.json())

Remember, we use 4 trailing zeroes, this means this Space has a risk limit of €1,000.

In this example, we create a Space with the name ‘My Space’ and description ‘I want to buy ETFs with this Space’.

Altering your Space 🛰️

If you’ve made a mistake in naming your Space, you can always alter its details, specifically the name, description and risk limit. You can do that with a PUT request as follows:

import requests
import json

request = requests.put("https://paper-trading.lemon.markets/v1/spaces/{space_id}/",
          data=json.dumps({
              "description": "I've added more money to My Space",
              "risk_limit": 50000000,
            }), headers={"Authorization": "Bearer YOUR-API-KEY"})

print(request.json())

You’ll need to replace {space_id} with your own Space ID.

Now, My Space has a new description and a higher risk limit.

Deleting your Space 👽

If you don’t need your Space anymore, you can delete it with the following DELETE request (proceed with caution because this action is not reversible):

import requests

request = requests.delete("https://paper-trading.lemon.markets/v1/spaces/{space_id}/", 
                          headers={"Authorization": "Bearer YOUR-API-KEY"})

print(request.json())

It’s important to note that you can only delete Spaces that do not hold any open positions or pending orders. You must close out of all your positions before deleting a Space.

---

That’s all there is to know about Space creation, deletion, updates and retrieval. Do you have any additional questions? Feel free to leave them below or reach out to us via Slack.

If you’re not yet signed-up to lemon.markets, you can do that here. We’d love to have you on board! 🚀

See you soon,

Joanne 🍋