Skip to main content

Working with Orders


A big part of using lemon.markets will evolve around building a trading product that eventually places an order at the stock market via our API. In this documentation section, we want to walk you through the whole process of doing that - from getting access to our API to retrieving market data, identifying the stocks you want to buy, eventually buying them and, last but not least, seeing all orders that have already been placed and monitoring their status. Alright, let's dive right in.

Getting Access#

Most requests with the lemon.markets API will require authentification, so it is crucial that you get access through an access token before making requests. Below find an illustration that explains the authentication process. Find deatiled information in the authentication chapter.

Authentication Process

Placing an Order#

Whenever you want to buy or sell an instrument, we provide a simple endpoint to do so. In general, orders are always related to a specific space, which is why you will always go via a space (identified through its UUID) in the request URL (as you will see in the following). However, before you place an order, it is important to know that there are different types of orders between which we distinguish and that influence how and when they are executed. Below, find more information about order types:

TypeDescription
Market OrderThe order is immediately executed at the next possible price.
Stop Market OrderOnce the stop price is met, the order is converted into a market order. After that, the order is executed immediately at the next possible price.
Limit OrderThe order is executed once the limit price is reached.
Stop Limit OrderOnce the stop price is met, the order is converted into a limit order. Then, the order is executed once the limit price is met.
You do not have to specify an order type!

We recognize the type of order automatically by looking at the query parameters. For instance, if you provide only a stop_price, the order is a Stop Market Order. If you provide both a stop_price and a limit_price, the order will be a Stop Limit Order. If you only provide the limit_price, the order will be a Limit Order. If you provide nothing, the order will be executed as a Market Order at the next available price.

Risk Surcharge when placing a Market Order

When you place a market order, we add a small risk surcharge on the latest price to cover potential price fluctations. So theoretically, if the latest price was 10€, you would need slightly more than 10€ Cash to Invest to be able to place the order.


POST Create an order#

Alright, now that we know all there is to know about different order types, let us actually place an order. This works via the following endpoint:

https://paper-trading.lemon.markets/rest/v1/spaces/{space_uuid}/orders/

This endpoint lets you create an order, meaning that you can buy or sell stocks, bonds, funds, ETFs or warrants. We need to be able to uniquely identify what exactly you want to buy. The way to do that with our API is to specify the International Securities Identification Number (ISIN) in your POST request. Below, find the specifics for the POST Order request.

Path ParametersTypeDetails
space_uuid
required
stringThe UUID of the space you want to place the order with.
HeadersTypeDetails
Authorization
required
stringBearer {TOKEN_KEY}
Request Body ParametersTypeDetails
isin
required
stringISIN of an instrument
valid_until
required
numberUTC UNIX Timestamp in seconds or JS Timestamp (see here). Can be any date in the future.
side
required
string"buy" or "sell"
quantity
required
intThe amount of shares you want to buy
stop_price
optional
numberSee here for information on numbers format
limit_price
optional
numberSee here for information on numbers format

Code Example#

Python
JavaScript
1 2 3 4 5 6 7 import requests request = requests.post("null", data={"isin": "null", "valid_until": null, "side" : "null", "quantity": 0},headers={"Authorization": "Bearer null"}) print(request.json())
Select side
Select Space


PUT Activate an order#

After you submitted an order using the POST request specified above, you will need to activate the order to actually place it.

You can do this by using the request URL:

https://paper-trading.lemon.markets/rest/v1/spaces/{space_uuid}/orders/{uuid}/activate/

After you activated the order, it is submitted via our API. Use the following parameters to specify your request:

Path ParametersTypeDetails
space_uuid
required
stringThe UUID of the space you want to activate the order with.
uuid
required
stringThe UUID of the order you want to activate.
HeadersTypeDetails
Authorization
required
stringBearer {TOKEN_KEY}

Code Example#

Python
JavaScript
1 2 3 4 5 6 7 import requests request = requests.put("null", headers={"Authorization": "Bearer null"}) print(request.json())
Select Space


Seeing Your Orders#

Besides buying different instruments, you are obviously also interested in seeing orders that you previously placed. While you can get an overview in the spaces sub page in our dashboard, there is also an API endpoint that returns all of your orders for the respective space.

GET LIST all orders#

You can use this endpoint to get a list of all orders that you placed with our API. Additonally, you also have the option to filter the response to only get the orders you are specifically interested in. The request URL is the same as above:

https://paper-trading.lemon.markets/rest/v1/spaces/{space_uuid}/orders/

By specifying your GET request through its parameters, you have the chance to influence the API response. Specifically, you will stumble across the order status. It is important to understand the difference here.

StatusExplanation
inactiveThe order was placed, but has not been activated, yet.
activatedThe order has been activated.
in_progressThe order is currently executed.
executedThe order was successfully executed.
deletedThe order was deleted.
expiredThe order has expired.

Below, find the specifics for the GET Orders request :

Path ParametersTypeDetails
space_uuid
required
stringThe UUID of the space your orders were placed in.
HeadersTypeDetails
Authorization
required
stringBearer {TOKEN_KEY}
Query ParametersTypeDetails
created_at_until
optional
numberUTC UNIX Timestamp in seconds or JS Timestamp (see here). Can be any date in the future.
created_at_from
optional
numberUTC UNIX Timestamp in seconds or JS Timestamp (see here). Can be any date in the future.
side
optional
string"buy" or "sell"
type
optional
stringFilter for order type: "limit","market","stop_limit","stop_market",
status
optional
stringFilter for status: "inactive","active","in_progress","executed","deleted","expired"
limit
optional
integerRequired for pagination; default is 200.
offset
optional
integerRequired for pagination

Code Example#

Python
JavaScript
1 2 3 4 5 6 7 import requests request = requests.get("null", headers={"Authorization": "Bearer null"}) print(request.json())
Select Space


You can also access a single order if you are specifically interested in it.

GET Retrieve a single order#

Retrieving a single order works via the URL:

https://paper-trading.lemon.markets/rest/v1/spaces/{space_uuid}/orders/{uuid}/

Below, find the specifics to access a single order:

Path ParametersTypeDetails
space_uuid
required
stringThe UUID of the space your order was placed in.
uuid
required
stringThe UUID of the specific order you want to retrieve.
HeadersTypeDetails
Authorization
required
stringBearer {TOKEN_KEY}

Code Example#

Python
JavaScript
1 2 3 4 5 6 7 import requests request = requests.get("null", headers={"Authorization": "Bearer null"}) print(request.json())
Select Space


Deleting an Order#

You also have the possibility to delete an order (as long as the order status is inactive or active).

DELETE Delete an order#

To delete an open order, use the request URL:

https://paper-trading.lemon.markets/rest/v1/spaces/{space_uuid}/orders/{uuid}/

The request needs to specified as follows:

Path ParametersTypeDetails
space_uuid
required
stringThe UUID of the space your order was placed in.
uuid
required
stringThe UUID of the specific order you want to delete.
HeadersTypeDetails
Authorization
required
stringBearer {TOKEN_KEY}

Code Example#

Python
JavaScript
1 2 3 4 5 6 7 import requests request = requests.delete("null", headers={"Authorization": "Bearer null"}) print(request.json())
Select Space