Orders

We are in open beta

Everything related to lemon.markets is still very much work in progress. Please bear with us that some things are still a bit buggy or functionality is missing. We are really grateful if you share your feedback on Slack as this helps make lemon.markets a product we all want to use. Thank you :)

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 you need to specify in the request body. There are different types of orders (Market Order, Limit Order, Stop Market Order, Stop Limit Order) which we distinguish and that influence how and when they are executed. Using the request body parameters stop_price and limit_price, you can automatically define the type of order you wish to place. Find more information below. Everything related to Orders is part of the Trading API. See below how to combine the /orders/ endpoint with the Trading API base URL.

POST /orders/

To create a new order, make a POST request against the URL:

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

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

This endpoint lets you create an order, meaning that you can buy or sell stocks or ETFs using the lemon.markets API. We need to be able to uniquely identify what exactly you want to buy. Below, find the specifics for the POST Order request.

100 Orders/day in the Paper Money environment

You can create a maximum of 100 Orders per day in the Paper Money Environment.

Request

Specify your request as follows:

Header Parameters

Set your Authorization header in the format "Authorization: Bearer YOUR-API-KEY"

Request Body Parameters

Request Body

You can send your request using the following content-types:

application/json
application/x-www-form-urlencoded

Placing an Order 24/7

In the Paper Money environment, you can place orders all day everyday, even outside of the standard trading hours.
To do so, use "venue": "allday" in your request body. The order is then executed at the price of the last saved quote for the respective ISIN.

Internation Security Identification Number of the instrument you wish to buy or sell

ISO String date (YYYY-MM-DD). Order expires at the end of the specified day.
Maximum expiration date is 30 days in the future.

When limit_price and/or stop_price are set, the expires_at parameter is required. For a market order, the expires_at parameter is optional. In the case of a market order, the default value is the end of the same day.

Small hack: write expires_at="pxd" to let the Order be valid for x days (e.g. "p7d").

With this you can define whether you want to buy ('buy') or sell ('sell') a specific instrument

The amount of shares you want to buy. Limited to 1000 per request.

Market Identifier Code of Stock exchange you want to address. Default value is 'XMUN'.
Use "venue": "allday" for 24/7 order exeution (only in the Paper Money environment).

Identification Number of the space you want to place the order with

Stop Price for your Order.
Please see here for information on the numbers format in the Trading API.

Limit Price for your Order.
Please see here for information on the numbers format in the Trading API.

You do not have to specify an Order Type

The type of Order is automatically derived based on the request body parameters you specify. See the table below for more information on how Order types are related to Price types.

Specified Price in Request Body	Type of Order
Neither *stop_price* nor *limit_price*	*Market Order*. The order is immediately executed at the next possible price.
*stop_price*	*Stop Market Order*. Once 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.
*stop_price* & *limit_price*	*Stop Limit Order*. Once the stop price is met, the order is converted into a limit order. Then, the order is executed at the specified price or better (Buy Order: limit price or lower, Sell Order: limit price or higher).
*limit_price*	Limit Order. The order is executed at the specified price or better (Buy Order: limit price or lower, Sell Order: limit price or higher).

Price fluctation buffer when placing a Market Order

Please make sure that you have sufficient funds in your account to be able to place a market order. To account for price fluctuations, we can only accept the order when your funds are slightly higher than the order you want to place. Of course, this is only a precaution and does not result in any additional costs for you.

Your personal Notes you wish to attach to the Order

Your own unique idempotency key that prevents duplicate operations

Response

Response Parameters

Timestamp of your request

API returns "ok" when Order was successfully placed

Environment the request was placed in: "paper" or "money"

International Securities Identification Number of instrument

Timestamp of point in time until order is valid.

Either "buy" or "sell"

Amount of instruments you specified for order.

Stop price for order. "null" if not specified.

Limit price for order. "null" if not specified.

Market Identifier Code for trading venue the order was placed at.

Identification Number of the space you placed the order with

Estimation from our end for what price the Order will be executed

Unique Order Identification Number

Status the Order is currently in: 'inactive', 'activated', 'open' (Real Money only), 'in_progress', 'canceling','executed', 'canceled' or 'expired'

Your personal Notes you attached to the Order

Your own unique idempotency key that prevents duplicate operations

Charge for placed order

Timestamp at which the charge was generated

API Key you created the order with

Regulatory Information

Costs for placing the Order

Costs for placing the Order as percentage value

Running costs for Order

Running costs for Order as percentage value

Costs for Product

Costs for Product as percentage value

Costs for exiting

Costs for exiting as percentage value

Expected yield reduction in first year

Expected yield reduction in following year

Expected yield reduction in exit year

Key Investors Information Document, only at ETFs

Legal disclaimer for placing the Order

Check our Error Handling Page for specific information on error types.

Request

1import requests
2import json
3
4request = requests.post("https://paper-trading.lemon.markets/v1/orders/",
5          data=json.dumps({
6              "isin": "US19260Q1076",
7              "expires_at": "2021-11-25",
8              "side": "buy",
9              "stop_price": 5000000,
10              "limit_price": 5300000,
11              "quantity": 1,
12              "venue": "XMUN",
13              "space_id": "123456789",
14              "notes": "I want to attach a note to this order"
15              "idempotency": "1234abcd"
16            }), headers={"Authorization": "Bearer YOUR-API-KEY"})
17print(request.json())
18

Response

1{
2  "time":"2021-11-21T19:34:45.071+00:00",
3  "status": "ok",
4  "mode":"paper",
5  "results": {
6    "created_at": "2021-11-15T13:58:19.981+00:00",
7    "id": "ord_pyPGQggmmj0jhlLHw2nfM92Hm9PmgTYq9K",
8    "status": "inactive",
9    "regulatory_information": {
10      "costs_entry": 20000,
11      "costs_entry_pct": "0.30%",
12      "costs_running": 0,
13      "costs_running_pct": "0.00%",
14      "costs_product": 0,
15      "costs_product_pct": "0.00%",
16      "costs_exit": 20000,
17      "costs_exit_pct": "0.30%",
18      "yield_reduction_year": 20000,
19      "yield_reduction_year_pct": "0.30%",
20      "yield_reduction_year_following": 0,
21      "yield_reduction_year_following_pct": "0.00%",
22      "yield_reduction_year_exit": 20000,
23      "yield_reduction_year_exit_pct": "0.30%",
24      "estimated_holding_duration_years": "5",
25      "estimated_yield_reduction_total": 40000,
26      "estimated_yield_reduction_total_pct": "0.61%",
27      "KIID": "text",
28      "legal_disclaimer": "text"
29    },
30    "isin": "DE0008232125",
31    "expires_at": "2021-11-07T22:59:00.000+00:00",
32    "side": "buy",
33    "quantity": 1,
34    "stop_price": None,
35    "limit_price": None,
36    "venue": "xmun",
37    "space_id": "sp_pyJKLffGGDyV5j7rxtG4YnfGwHBGk3njBy",
38    "estimated_price": 66140000,
39    "notes": "I want to attach a note to this order"
40    "idempotency": "1234abcd"
41    "charge": 20000,
42    "chargeable_at": "2021-12-10T07:57:12.628+00:00"
43    "key_creation_id": "apk_pyJKKbbDDNympXsVwZzPp2nBVlTMTLRmxy"
44  }
45}
46

Activating an Order

After you submitted an order in a manual space you need to activate the order to actually place it. This Two-Factor Authentication (2FA) is an additional level of security for you, so you always have full control over all placed orders. For all orders placed in the real money environment, we offer the lemon.markets mobile app to let you conveniently activate your orders. However, if you want to activate a paper money order or are interested in building your own 2FA experience, you can use the /activate endpoint to do so.

Activating an Order in the Mobile App

The lemon.markets mobile app offers a simple way to activate your real money orders. As soon as an order is placed, the order appears in the app under "Approvals" and you can activate it there with one simple button click. The process looks about like this:

1. Get Push Notification for Order	2. Activate your Order in the App	3. Receive Activation Confirmation

POST /orders/{order_id}/activate/

If you want to activate a paper money order or are interested in building your own 2FA experience you can use the /activate endpoint with the following request URLs:

https://paper-trading.lemon.markets/v1/orders/{order_id}/activate/

for Paper Money Orders, or

https://trading.lemon.markets/v1/orders/{order_id}/activate/

for Real Money Orders.

After you activated the order, it is routed to the trading venue via our API.

Request

Specify your request as follows:

Header Parameters

Set your Authorization header in the format "Authorization: Bearer YOUR-API-KEY"

Request Body

You can send your request using the following content-types:

application/json
application/x-www-form-urlencoded

Request Body Parameters

PIN to activate an order. If you want to activate a real money order use the 4-digit PIN you set during your onboarding process. If you want to activate a paper money order you can use any random 4-digit PIN or send the request without request body.

Response

Response Parameters

Timestamp of your request

Environment the request was placed in: "paper" or "money"

The API returns "ok" when the order was successfully activated.

Check our Error Handling Page for specific information on error types.

Request

1import requests
2import json
3
4request = requests.post("https://paper-trading.lemon.markets/v1/orders/{order_id}/activate/",
5          data=json.dumps({
6              "pin": "7652"
7            }), headers={"Authorization": "Bearer YOUR-API-KEY"})
8print(request.json())
9

Retrieving your Orders

Besides buying different instruments, you might 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 /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. Create a GET Request against the following URLs:

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

to see your Paper Money Orders, and

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

to see your Real Money 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.

Status	Explanation
inactive	The order was placed, but has not been routed to the Stock Exchange, yet.
activated	The order has been routed to the Stock Exchange.
open	The stock exchange confirmed to have received the order (Real Money only)
canceling	The request to cancel the order is being routed to the stock exchange
canceled	The stock exchange successfully canceled the order.
in_progress	The order is currently executed at the stock exchange.
executed	The order was successfully executed at the stock exchange.
expired	The order has expired.

Request

Specify your request as follows:

Header Parameters

Set your Authorization header in the format "Authorization: Bearer YOUR-API-KEY"

Query Parameters

Add this Query Parameter to only see the orders of a specific space.

Specify an ISO date string (YYYY-MM-DD) to get only orders from a specific date on.

Specify an ISO date string (YYYY-MM-DD) to get only orders until a specific date.

Add this Query Parameter to only see orders from a specific instrument.

Filter to either only see "buy" or "sell" orders.

Filter for status 'inactive', 'activated', 'open' (Real Money only), 'in_progress', 'canceling','executed', 'canceled' or 'expired'

Filter for different types of orders: market, stop, limit, stop_limit

Filter for a specific API you created orders with

Required for Pagination. Limit of displayed results on one page

Required for Pagination. Results page you wish to display

Response

Response Parameters

Timestamp of your request

API returns "ok" when Orders were successfully retrieved

Environment the request was placed in: "paper" or "money"

Unique Order Identification Number

International Security Identification Number (ISIN) for instrument bough or sold with this Order

Title of bought or sold instrument

Timestamp at which the Order expires

Timestamp at which the Order was created

A Order can be one of two sides - either "buy" or "sell"

Number of Instruments specified in Order

Stop Price defined for the Order

Limit Price defined for the Order

Estimated Price the Order will be executed at (only for Market Orders)

Estimated Price the Order will be executed at (only for Market Orders), multiplied by the Order quantity

Market Identifier Code of Trading Venue the Order was placed at

Order Status - either 'inactive', 'activated', 'open' (Real Money only), 'in_progress', 'canceling','executed', 'canceled' or 'expired'

ID of Space the Order was placed in

Order Type: market, limit, stop, stop_limit

Amount of Instruments specified in Order

Price the Order was executed at

Price the Order was executed at, multiplied by the Order quantity

Timestamp the Order was executed at

Timestamp the Order was (potentially) rejected at

Your personal Notes you attached to the Order

Charge for placed order

Timestamp at which the charge was generated

API Key you created the order with

API Key you activated the order with (can be different than API key created the order with). When order was activated via mobile app, the API will return null here.

Pagination: previous page

Pagination: next page

Pagination: total number of results

Pagination: current page

Pagination: total number of pages

Your own unique idempotency key that prevents duplicate operations

Regulatory Information

Costs for placing the Order

Costs for placing the Order as percentage value

Running costs for Order

Running costs for Order as percentage value

Costs for Product

Costs for Product as percentage value

Costs for exiting

Costs for exiting as percentage value

Expected yield reduction in first year

Expected yield reduction in following year

Expected yield reduction in exit year

Key Investors Information Document, only at ETFs

Legal disclaimer for placing the Order

Check our Error Handling Page for specific information on error types.

Request

1import requests
2import json
3
4request = requests.get("https://paper-trading.lemon.markets/v1/orders/?side=buy&status=executed&from=2021-11-01", headers={"Authorization": "Bearer YOUR-API-KEY"})
5print(request.json())
6

Response

1{
2  "time":"2021-11-21T19:34:45.071+00:00",
3  "status": "ok",
4  "mode":"paper",
5  "results": 
6  [
7    {
8      "id": "ord_pyPGQhhllz0mypLHw2nfM67Gm9PmgTYq0J",
9      "isin": "DE0008232125",
10      "isin_title": "DEUTSCHE LUFTHANSA AG",
11      "expires_at": "2021-11-07T22:59:00.000+00:00",
12      "created_at": "2021-11-04T12:25:30.063+00:00",
13      "side": "buy",
14      "quantity": 1000,
15      "stop_price": None,
16      "limit_price": None,
17      "estimated_price": 66140000,
18      "estimated_price_total": 66140000,
19      "venue": "xmun",
20      "status": "inactive",
21      "space_id": "sp_pyHJKffGGDyV4m8rxtK/YnfGwBNHk3njBy",
22      "type": "market",
23      "executed_quantity": 1,
24      "executed_price": 2965000,
25      "executed_price_total": 2965000,
26      "executed_at": 2021-11-04T12:25:12.402+00:00,
27      "rejected_at": None,
28      "notes": "My Notes",
29      "charge": 20000,
30      "chargeable_at": "2021-12-10T07:57:12.628+00:00"
31      "key_creation_id": "apk_pyJHHbbDDNympXsVwZzPp2nNBlTMTLRmxy",
32      "key_activation_id": "apk_pyJHHbbDDNympXsVwZzPp2nNBlTMTLRmxy",
33      "regulatory_information": {
34          "costs_entry": 20000,
35          "costs_entry_pct": "0.30%",
36          "costs_running": 0,
37          "costs_running_pct": "0.00%",
38          "costs_product": 0,
39          "costs_product_pct": "0.00%",
40          "costs_exit": 20000,
41          "costs_exit_pct": "0.30%",
42          "yield_reduction_year": 20000,
43          "yield_reduction_year_pct": "0.30%",
44          "yield_reduction_year_following": 0,
45          "yield_reduction_year_following_pct": "0.00%",
46          "yield_reduction_year_exit": 20000,
47          "yield_reduction_year_exit_pct": "0.30%",
48          "estimated_holding_duration_years": "5",
49          "estimated_yield_reduction_total": 40000,
50          "estimated_yield_reduction_total_pct": "0.61%",
51          "KIID": "text",
52          "legal_disclaimer": "text"
53      }
54      "idempotency": "1235abcd"
55    }
56  ]
57  'previous': 'https://paper-trading.lemon.markets/v1/orders/?limit=10&page=1', 
58  'next': 'https://paper-trading.lemon.markets/v1/orders/?limit=10&page=3', 
59  'total': 33, 
60  'page': 2, 
61  'pages': 4
62}
63

GET /orders/{order_id}/

To retrieve a single order, use the following request URLs:

https://paper-trading.lemon.markets/v1/orders/{order_id}/

to see a specific Paper Money Order, and

https://trading.lemon.markets/v1/orders/{order_id}/

to see a specific Real Money Order.

Request

Specify your request as follows:

Path Parameters

The ID of the order you want to retrieve

Header Parameters

Set your Authorization header in the format "Authorization: Bearer YOUR-API-KEY"

Response

Response Parameters

Timestamp of your request

API returns "ok" when Orders were successfully retrieved

Environment the request was placed in: "paper" or "money"

Unique Order Identification Number

International Security Identification Number (ISIN) for instrument bough or sold with this Order

Title of bought or sold instrument

Timestamp at which the Order expires

Timestamp at which the Order was created

A Order can be one of two sides - either "buy" or "sell"

Number of Instruments specified in Order

Stop Price defined for the Order

Limit Price defined for the Order

Estimated Price the Order will be executed at (only for Market Orders)

Estimated Price the Order will be executed at (only for Market Orders), multiplied by the Order quantity

Market Identifier Code of Trading Venue the Order was placed at

Order Status - either 'inactive', 'activated', 'open' (Real Money only), 'in_progress', 'canceling','executed', 'canceled' or 'expired'

ID of Space the Order was placed in

Order Type: market, limit, stop, stop_limit

Amount of Instruments specified in Order

Price the Order was executed at

Price the Order was executed at, multiplied by the Order quantity

Timestamp the Order was executed at

Timestamp the Order was (potentially) rejected at

Your personal Notes you attached to the Order

Charge for placed order

Timestamp at which the charge was generated

API Key you created the order with

API Key you activated the order with (can be different than API key created the order with)

Your own unique idempotency key that prevents duplicate operations

Regulatory Information

Costs for placing the Order

Costs for placing the Order as percentage value

Running costs for Order

Running costs for Order as percentage value

Costs for Product

Costs for Product as percentage value

Costs for exiting

Costs for exiting as percentage value

Expected yield reduction in first year

Expected yield reduction in following year

Expected yield reduction in exit year

Key Investors Information Document, only at ETFs

Legal disclaimer for placing the Order

Check our Error Handling Page for specific information on error types.

Request

1import requests
2import json
3
4request = requests.get("https://paper-trading.lemon.markets/v1/orders/{order_id}/", headers={"Authorization": "Bearer YOUR-API-KEY"})
5print(request.json())
6

Response

1
2  {
3  "time":"2021-11-21T19:34:45.071+00:00",
4  "status": "ok",
5  "mode":"paper",
6  "results": {
7    "id": "ord_pyPGQhhllz0mypLHw2nfM67Gm9PmgTYq0J",
8    "isin": "DE0008232125",
9    "isin_title": "DEUTSCHE LUFTHANSA AG",
10    "expires_at": "2021-11-07T22:59:00.000+00:00",
11    "created_at": "2021-11-04T12:25:30.063+00:00",
12    "side": "buy",
13    "quantity": 1000,
14    "stop_price": None,
15    "limit_price": None,
16    "estimated_price": 66140000,
17    "estimated_price_total": 66140000,
18    "venue": "xmun",
19    "status": "inactive",
20    "space_id": "sp_pyHJKffGGDyV4m8rxtK/YnfGwBNHk3njBy",
21    "type": "market",
22    "executed_quantity": 1,
23    "executed_price": 2965000,
24    "executed_price_total": 2965000,
25    "executed_at": 2021-11-04T12:25:12.402+00:00,
26    "rejected_at": None,
27    "notes": "My Notes", 
28    "charge": 20000,
29    "chargeable_at": "2021-12-10T07:57:12.628+00:00"
30    "key_creation_id": "apk_pyJHHbbDDNympXsVwZzPp2nNBlTMTLRmxy",
31    "key_activation_id": "apk_pyJHHbbDDNympXsVwZzPp2nNBlTMTLRmxy",
32    "regulatory_information": {
33        "costs_entry": 20000,
34        "costs_entry_pct": "0.30%",
35        "costs_running": 0,
36        "costs_running_pct": "0.00%",
37        "costs_product": 0,
38        "costs_product_pct": "0.00%",
39        "costs_exit": 20000,
40        "costs_exit_pct": "0.30%",
41        "yield_reduction_year": 20000,
42        "yield_reduction_year_pct": "0.30%",
43        "yield_reduction_year_following": 0,
44        "yield_reduction_year_following_pct": "0.00%",
45        "yield_reduction_year_exit": 20000,
46        "yield_reduction_year_exit_pct": "0.30%",
47        "estimated_holding_duration_years": "5",
48        "estimated_yield_reduction_total": 40000,
49        "estimated_yield_reduction_total_pct": "0.61%",
50        "KIID": "text",
51        "legal_disclaimer": "text"
52    }
53    "idempotency": "1234abcd"
54  }
55}

Canceling an Order

You also have the option to cancel an order when the order status is inactive or activated. This means that only orders that have not yet been processed by the stock exchange can be canceled.

DELETE /orders/{order_id}/

To cancel an order, create a DELETE request against the following URLs:

https://paper-trading.lemon.markets/v1/orders/{order_id}/

to cancel a specific Paper Money Order, and

https://trading.lemon.markets/v1/orders/{order_id}/

to cancel a specific Real Money Order.

Request

Specify your request as follows:

Path Parameters

ID of the order you wish to cancel.

Header Parameters

Set your Authorization header in the format "Authorization: Bearer YOUR-API-KEY"

Response

Response Parameters

Timestamp of your request

API returns "ok" when order was successfully canceled

Environment the request was placed in: "paper" or "money"

Automatic order cancellation once per day

We have a job running that automatically cancels all orders with status canceling and expired at the end of each day.

See below for specific information on the process of canceling an order and the different order statuses during it.

Status	Explanation
canceling	Right after you send your DELETE request, the order status changes to canceling, which indicates that the cancel request has been transmitted to, but not yet processed by the stock exchange.
executed	If the stock exchange is not able to cancel the order and instead executes it, the order status changes to executed.
canceled	If the stock exchange is able to cancel the order, the order status changes to canceled. For orders that were not yet activated (status inactive), the order status never changes to canceling, but instead immediately changes to canceled.

Check our Error Handling Page for specific information on error types.

Request

1import requests
2import json
3
4request = requests.delete("https://paper-trading.lemon.markets/v1/orders/{order_id}/", headers={"Authorization": "Bearer YOUR-API-KEY"})
5print(request.json())
6