Orders

Placing an Order

Whenever you want to buy or sell an instrument, we provide a simple endpoint to do so: the /orders endpoint. In general, 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

You can create an order in the Paper Trading and in the Live Trading Environment, which depends on the request URL and the API Key you are using. To create a new Paper Trading order, make a POST request against the URL:

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

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

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

Request

1000 orders/day in the Paper Money environment

You can create up to 1000 orders per day in the Paper Money environment.

To create a new order, specify your request as follows:

Header Parameters

Set your Authorization header in the format "Authorization: Bearer YOUR-API-KEY"
(see the example in the code snippet on the right)

Request Body Parameters

Request Body

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

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

This is the International Security Identification Number that uniquely identifies the instrument you wish to buy or sell.

Specify the expiry date. The order expires at the end of the specified day. The Maximum expiration date is 30 days in the future.

When limit_price or stop_price are set, this parameter is required.
For a market order, this parameter is optional.

Default value: End of the current trading day (for market orders).

Two formats are supported:

ISO8601 date: YYYY-MM-DD
Period length in days, e.g. 14D to specify two weeks.

Read more ↘

Use this attribute to define whether you want to buy ('buy') or sell ('sell') a specific instrument.

Use this attribute to define the number of shares you want to buy. This is limited to 25,000€ estimated order price per request.

If this limit restricts you in your development process, please contact us at support@lemon.markets.

Read more ↘

The minimum order amount in both Paper and Live Trading is 50€

Specify the stock exchange you want to place the order at using its Market Idenfier Code (MIC). In Paper Trading, you can use allday for 24/7 order execution. The order is then executed at the latest quote saved.

Default value: XMUN (Munich Stock Exchange, Gettex).

Optional Attributes

Use this attribute to define a Stop Price for your Order.

Please see Numbers & Dates for more information on the number format in the Trading API.

Use this attribute to define a Limit Price for your Order.

Please see Numbers & Dates for more information on the number format in the Trading API.

Use this attribute to attach your personal Notes to the Order

You can set your own unique idempotency key to prevent duplicate operations. Subsequent requests with the same idempotency key will then not go through and throw an error message. This means you cannot place the same order twice.

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.

Response

Response Parameters

This is the Timestamp for when the order was created.

This is the unique Order Identification Number, which you can later use to activate your order.

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

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
executed: The order was successfully executed at the stock exchange
expired: The order has expired

Read more ↘

This is the International Securities Identification Number of the instrument specified in that order

This is the Timestamp until when the order is valid

This can be either "buy" or "sell"

This is the amount of instruments specified in the order

This is the Stop price for the order. "null" if not specified.

This is the Limit price for the order. "null" if not specified.

This is the Market Identifier Code of the trading venue the order was placed at (default is XMUN).

This is an estimation from our end for what price the order will be executed

This is the charge for the placed order

Other Attributes

This is the Timestamp of your request

API returns "ok" when Order was successfully placed

This is the environment the request was placed in: "paper" or "money"

These are your personal Notes you attached to the Order

This is a unique idempotency key that prevents duplicate operations. Subsequent requests with the same idempotency key will then not go through and throw an error message. This means you cannot place the same order twice.

Timestamp at which the charge was generated

This is the API Key the order was created with

Regulatory Information

These are the costs for placing the Order

These are the costs for placing the Order as percentage value

These are the running costs for the order

These are the running costs for the order as percentage value

These are the product costs for the order

These are the product costs for the order as percentage value

These are the exit costs for the order

These are the exit costs for the order as percentage value

This is the expected yield reduction in the first year

This is the expected yield reduction in the following year

This is the expected yield reduction in the exit year

This is the Key Investors Information Document, only at ETFs

This is a legal disclaimer for placing the Order

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

POST/orders

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": "1D",
8              "side": "buy",
9              "quantity": 1,
10              "venue": "XMUN",
11            }),
12          headers={"Authorization": "Bearer YOUR-API-KEY"})
13print(request.json())

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": null,
35    "limit_price": null,
36    "venue": "xmun",
37    "estimated_price": 66140000,
38    "notes": "I want to attach a note to this order",
39    "idempotency": "1234abcd",
40    "charge": 20000,
41    "chargeable_at": "2021-12-10T07:57:12.628+00:00",
42    "key_creation_id": "apk_pyJKKbbDDNympXsVwZzPp2nBVlTMTLRmxy"
43  }
44}
45

Activating an Order

After you submitted an order 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:

Mobile Phone Screen displaying Push Notification for Confirmation

Mobile Phone Screen displaying Prompt for Confirmation

Mobile Phone Screen displaying Order Confirmation Result

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.

Use this URL to activate a Paper Trading order:

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

Use this URL to activate a Live Trading order:

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

for Real Money Orders.

After you activated the order, it is routed to the stock exchange.

Request

To activate an order, specify your request as follows:

Header Parameters

Set your Authorization header in the format "Authorization: Bearer YOUR-API-KEY"
(see the example in the code snippet on the right)

Request Body

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

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

Request Body Parameters

You need to set a PIN in the request body 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

This is the Timestamp of your request

This is the 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.

POST/orders/{order_id}/activate

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            }),
8          headers={"Authorization": "Bearer YOUR-API-KEY"})
9print(request.json())

Response

1{
2  "time":"2021-11-21T19:34:45.071+00:00",
3  "mode":"paper",
4  "status": "ok"
5}

Retrieving your Orders

Besides placing order, you can also use the API to retrieve your previous and current orders.
While you can get an overview in your dashboard, there is also an API endpoint that returns all of your orders.

GET /orders

You can use this endpoint to get a list of all orders that you placed with the lemon.markets API API. Additonally, you also have the option to filter the response to only get the orders you are specifically interested in.

To retrieve your Paper Trading Orders, create a GET Request against the following URL:

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

To retrieve your Paper Trading Orders, create a GET Request against the following URL:

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

Request

To retrieve your orders, specify your request as follows:

Header Parameters

Set your Authorization header in the format "Authorization: Bearer YOUR-API-KEY"
(see the example in the code snippet on the right)

Query Parameters

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.

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
executed: The order was successfully executed at the stock exchange
expired: The order has expired

NOTE: You can specify more than one order status per request:

Concatenate multiple state using a comma like this: &status=inactive,open, or…
provide more than just one status query item like this &status=inactive&status=open.

Read more ↘

Other Query Parameters

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

Filter for a specific API you created orders with

This parameter is required to influence the Pagination. Use it to define the limit of displayed results on one page.
The default value is 10, the maximum number is 100.

This parameter is required to influence the Pagination. Use it to define the specific results page you wish to display.

Response

Response Parameters

This is the unique Order Identification Number

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

This is the Title of the instrument bought or sold with this order

This is the Timestamp at which the Order expires

This is the Timestamp at which the Order was created

This is the side of an order. An Order can be one of two sides - either "buy" or "sell"

This is the number of Instruments specified in the Order

This is the Stop Price defined for the Order. "null" if Stop Price is not set.

This is the Limit Price defined for the Order. "null" if Stop Price is not set.

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

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

This is the Market Identifier Code of the Trading Venue the Order was placed at

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

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
executed: The order was successfully executed at the stock exchange
expired: The order has expired

Read more ↘

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

Pagination

Pagination attribute: this is a URL of the previous page

Pagination attribute: this is a URL of the next page

Pagination attribute: this is the total number of results

Pagination attribute: this is the current page number

Pagination attribute: this is the total number of pages

Other Attributes

This is the Timestamp of the request

API returns "ok" when Orders were successfully retrieved

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

This is the Order Type: market, limit, stop, stop_limit

This is the amount of Instruments to be bought or sold, as specified in the Order

This is the Price the Order was executed at

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

This is the Timestamp the Order was executed at

This is the Timestamp the Order was rejected at (only for orders that were not executed)

These are the personal Notes you attached to the Order

This is the Charge for placed order

This is the Timestamp at which the charge was generated

This is the API Key the Order was created with

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

Read more ↘

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

GET/orders

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

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": null,
16      "limit_price": null,
17      "estimated_price": 66140000,
18      "estimated_price_total": 66140000,
19      "venue": "xmun",
20      "status": "inactive",
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": null,
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": "1235abcd"
54    }
55  ],
56  "previous": "https://paper-trading.lemon.markets/v1/orders?limit=10&page=1", 
57  "next": "https://paper-trading.lemon.markets/v1/orders?limit=10&page=3", 
58  "total": 33, 
59  "page": 2, 
60  "pages": 4
61}
62

GET /orders/{order_id}

You can also retrieve a single order directly.

To retrieve a single Paper Order, use the following request URL:

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

To retrieve a single Live Trading Order, use the following request URL:

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

Request

To retrieve a single Order, specify your request as follows:

Path Parameters

This is the unique Identification Number of the Order you want to retrieve

Header Parameters

Set your Authorization header in the format "Authorization: Bearer YOUR-API-KEY"
(see the example in the code snippet on the right)

Response

Response Parameters

This is the unique Order Identification Number

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

This is the Title of the instrument bought or sold with this order

This is the Timestamp at which the Order expires

This is the Timestamp at which the Order was created

This is the side of an order. An Order can be one of two sides - either "buy" or "sell"

This is the number of Instruments specified in the Order

This is the Stop Price defined for the Order. "null" if Stop Price is not set.

This is the Limit Price defined for the Order. "null" if Stop Price is not set.

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

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

This is the Market Identifier Code of the Trading Venue the Order was placed at

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

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
executed: The order was successfully executed at the stock exchange
expired: The order has expired

Read more ↘

Other Attributes

This is the Timestamp of the request

API returns "ok" when Orders were successfully retrieved

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

This is the Order Type: market, limit, stop, stop_limit

This is the amount of Instruments to be bought or sold, as specified in the Order

This is the Price the Order was executed at

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

This is the Timestamp the Order was executed at

This is the Timestamp the Order was rejected at (only for orders that were not executed)

These are the personal Notes you attached to the Order

This is the Charge for placed order

This is the Timestamp at which the charge was generated

This is the API Key the Order was created with

Read more ↘

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.

GET/orders/{order_id}

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

Response

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

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 API.

To cancel a Paper Order, use the following request URL:

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

To cancel a Live Trading Order, use the following request URL:

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

Request

To cancel a specific Order, specify your request as follows:

Path Parameters

Unique Identification Number of the order you wish to cancel.

Header Parameters

Set your Authorization header in the format "Authorization: Bearer YOUR-API-KEY"
(see the example in the code snippet on the right)

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.

DELETE/orders/{order_id}

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

Response

1{
2  "time":"2021-11-21T19:34:45.071+00:00",
3  "status": "ok",
4  "mode":"paper"
5}