You can create up to 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.
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
orstop_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.
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.
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
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
4paper_trading_key = 'YOUR-PAPER-TRADING-KEY'
5request = requests.post("https://paper-trading.lemon.markets/v1/orders",
6 data=json.dumps({
7 "isin": "US19260Q1076",
8 "expires_at": "1D",
9 "side": "buy",
10 "quantity": 1,
11 "venue": "XMUN",
12 }),
13 headers={"Authorization": f"Bearer {paper_trading_key}"})
14print(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": 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. 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.
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
4paper_trading_key = 'YOUR-PAPER-TRADING-KEY'
5request = requests.post("https://paper-trading.lemon.markets/v1/orders/{order_id}/activate",
6 data=json.dumps({
7 "pin": "7652"
8 }),
9 headers={"Authorization": f"Bearer {paper_trading_key}"})
10print(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 exchangecanceled
: The stock exchange successfully canceled the orderexecuted
: The order was successfully executed at the stock exchangeexpired
: 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
.
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
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
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.
Check our Error Handling Page for specific information on error types.
1import requests
2import json
3
4paper_trading_key = 'YOUR-PAPER-TRADING-KEY'
5request = requests.get("https://paper-trading.lemon.markets/v1/orders",
6 headers={"Authorization": f"Bearer {paper_trading_key}"})
7print(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": 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:
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
4paper_trading_key = 'YOUR-PAPER-TRADING-KEY'
5request = requests.get("https://paper-trading.lemon.markets/v1/orders/{order_id}",
6 headers={"Authorization": f"Bearer {paper_trading_key}"})
7print(request.json())
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:
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
4paper_trading_key = 'YOUR-PAPER-TRADING-KEY'
5request = requests.delete("https://paper-trading.lemon.markets/v1/orders/{order_id}",
6 headers={"Authorization": f"Bearer {paper_trading_key}"})
7print(request.json())
1{
2 "time":"2021-11-21T19:34:45.071+00:00",
3 "status": "ok",
4 "mode":"paper"
5}