You can create a maximum of 1000 Orders per day in the Paper Money Environment.
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:
To create a new Live Trading order, make a POST request against the URL:
Request
1000 Orders/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.
Use this attribute to specify when you want your order to expire by defining an ISO String date (YYYY-MM-DD).
The order then expires at the end of the specified day.
The 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").
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.
Use this attribute to specify the Market Identifier Code (MIC) of the stock exchange you want to place the order at.
The Default value is 'XMUN' (Munich Stock Exchange).
You can use "venue": "allday" for 24/7 order exeution (only in the Paper Money environment). The order is then executed at
the last saved quote.
Optional Attributes
Use this attribute to define a Stop Price for your Order.
Please see here
for information on the numbers format in the Trading API.
Use this attribute to define a Limit Price for your Order.
Please see here
for information on the numbers 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
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.
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 "quantity": 1,
10 "venue": "XMUN",
11 }),
12 headers={"Authorization": "Bearer YOUR-API-KEY"})
13print(request.json())
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 "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:
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.
Use this URL to activate a Paper Trading order:
Use this URL to activate a Live Trading order:
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.
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())
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:
To retrieve your Paper Trading Orders, create a GET Request against the following URL:
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
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
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
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.
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
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.
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())
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 "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": "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:
To retrieve a single Live Trading Order, use the following request URL:
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
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
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.
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.
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())
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 "type": "market",
21 "executed_quantity": 1,
22 "executed_price": 2965000,
23 "executed_price_total": 2965000,
24 "executed_at": 2021-11-04T12:25:12.402+00:00,
25 "rejected_at": None,
26 "notes": "My Notes",
27 "charge": 20000,
28 "chargeable_at": "2021-12-10T07:57:12.628+00:00",
29 "key_creation_id": "apk_pyJHHbbDDNympXsVwZzPp2nNBlTMTLRmxy",
30 "key_activation_id": "apk_pyJHHbbDDNympXsVwZzPp2nNBlTMTLRmxy",
31 "regulatory_information": {
32 "costs_entry": 20000,
33 "costs_entry_pct": "0.30%",
34 "costs_running": 0,
35 "costs_running_pct": "0.00%",
36 "costs_product": 0,
37 "costs_product_pct": "0.00%",
38 "costs_exit": 20000,
39 "costs_exit_pct": "0.30%",
40 "yield_reduction_year": 20000,
41 "yield_reduction_year_pct": "0.30%",
42 "yield_reduction_year_following": 0,
43 "yield_reduction_year_following_pct": "0.00%",
44 "yield_reduction_year_exit": 20000,
45 "yield_reduction_year_exit_pct": "0.30%",
46 "estimated_holding_duration_years": "5",
47 "estimated_yield_reduction_total": 40000,
48 "estimated_yield_reduction_total_pct": "0.61%",
49 "KIID": "text",
50 "legal_disclaimer": "text"
51 },
52 "idempotency": "1234abcd"
53 }
54}
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:
To cancel a Live Trading Order, use the following request URL:
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.
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())
1{
2 "time":"2021-11-21T19:34:45.071+00:00",
3 "status": "ok",
4 "mode":"paper"
5}