Quickstart

Quickstart

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 :)

Wanna get started quickly and place your first Paper Money order within minutes? Then this page is for you. Below, we give you a quick overview of the steps you need to take to make your first request with the lemon.markets API. If you are interested in diving deeper: click the links in the respective sections. The process in our Quickstart Tutorial looks like this:


Authentication Process

Start your lemon.markets journey by signing up on our dashboard. Activate your account by clicking the confirmation link in the email we send you after you've signed up. You can log in afterwards and start using lemon.markets.

After activating your account, you are almost ready to start using our API. However, one step is missing: you need authentication to use the API. Most requests require authentication through an API Key. Find all your API Keys in the Dashboard. We provide you with a default API Key when you sign up, which is valid for one year but you also have the option to create additional custom API Keys in your Dashboard. Additionally, we also create a default space for you whose ID you can/need to include in your request as well. Using an API Key and the Space ID, you are ready to make your first request.

Let's take a look at one of the key functionalities of the lemon.markets Trading API: placing an order. All requests related to trading will be performed using the Trading API. In this Quickstart guide we will place a Paper Money order so all instructions are related to the Paper Money environment whose base URL is:

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

To place your first paper money order with the lemon.markets API, create a POSTrequest and use:

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

This endpoint lets you create an order, meaning that you can buy or sell stocks and ETFs.

Request

100 Orders/day in the Paper Money environment

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

Specify your request as follows:

Header Parameters

Authorization
string
required

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.


isin
string
required

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

expires_at
string
required

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").

side
string
required

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

quantity
int
required

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

venue
string
required

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

space_id
string
required

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

stop_price
number
optional

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

limit_price
number
optional

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

notes
string

Your personal Notes you wish to attach to the Order


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

time
string

Timestamp of your request

mode
string

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

status
string

API returns "ok" when Order was successfully placed

isin
string

International Securities Identification Number of instrument

expires_at
string

Timestamp of point in time until order is valid.

side
string

Either "buy" or "sell"

quantity
int

Amount of instruments you specified for order.

stop_price
int

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

limit_price
int

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

venue
string

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

space_id
string

Identification Number of the space you placed the order with

estimated_price
int

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

id
string

Unique Order Identification Number

status
string

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

notes
string

Your personal Notes you attached to the Order

Regulatory Information

See our Orders page for detailed information on Order costs and other regulatory information.

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

Response

1{
2  "time":"2021-11-21T19:34:45.071+00:00",
3  "mode": "paper",
4  "status": "ok",
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  }
41}
42

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. To activate an order you can use the lemon.markets mobile app. 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 Order2. Activate your Order in the App3. Receive Activation Confirmation
Order Push Notification Activate Order ScreenActivate Order Screen

Building your own 2FA experience

If you are interested in building your own 2FA experience, you can use our /orders/{order_id}/activate endpoint to do so. Find more information here.

Find detailed information about all things related to orders in the docs section Orders.

After you placed a few orders, you might be interested in seeing how our Portfolio looks like. Using the /portfolio endpoint, you can get in-depth information on all your portfolio items. In general, a portfolio item is the result of an executed order.

To request your portfolio items, use the follow request URLs:

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

for your Paper Money Portfolio and:

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

for your Real Money Portfolio.

Request

Specify your request as follows:

Header Parameters

Authorization
string
required

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

Query Parameters

isin
string
optional

Filter for a specific Instrument in your portfolio

space_id
string
optional

Filter for a specific Space in your portfolio

Response

Response Parameters

time
string

Timestamp of your request

mode
string

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

status
string

Shows status "ok" when portfolio was successfully retrieved

space_id
string

Identification Number of the space you placed the order with

isin
string

International Securities Identification Number of instrument

isin_title
string

Title of instrument

quantity
int

Number of current Instrument items in your Portfolio

buy_quantity
int

Number of purchased Instrument items

sell_quantity
int

Number of sold Instrument items

buy_price_avg
int

Average buy-in price

buy_price_min
int

Minimum buy-in price

buy_price_max
int

Maximum buy-in price

buy_price_avg_historical
int

Average historical buy-in price

sell_price_min
int

Minimum sell price

sell_price_max
int

Maximum sell price

sell_price_avg_historical
int

Average historical sell price

orders_total
int

Total number of orders for Portfolio item

sell_orders_total
int

Total number of sell orders for Portfolio item

buy_orders_total
int

Total number of buy orders for Portfolio item

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/portfolio/?isin=US88160R1014&space_id=sp_pyJKLffNNByV4m8rxtG4YnfGwKJGk3bnBy", headers={"Authorization": "Bearer YOUR-API-KEY"})
5print(request.json())
6      

Response

1{
2  "time": "2021-12-20T14:13:47.602+00:00",
3  "mode":"paper",
4  "status": "ok",
5  "results": [
6      {
7        "space_id": "sp_pyPFYssNNJyV4m8rxtK7LnfGwKLMk2njSv",
8        "isin": "US19260Q1076",
9        "isin_title": "COINBASE GLOBAL INC.",
10        "quantity": 1,
11        "buy_quantity": 1,
12        "sell_quantity": 0,
13        "buy_price_avg": 2965000,
14        "buy_price_min": 2965000,
15        "buy_price_max": 2965000,
16        "buy_price_avg_historical": 2965000,
17        "sell_price_min": null,
18        "sell_price_max": null,
19        "sell_price_avg_historical": null,
20        "orders_total": 1,
21        "sell_orders_total": 0,
22        "buy_orders_total": 1
23      },
24      {
25        "space_id": "sp_pyPFYssNNJyV4m8rxtK7LnfGwKLMk2njSv",
26        ...
27      }
28    ]
29}
30
31  

We hope that this docs section gave you a quick start. If you are interested in more detailed explanations: dive right into our docs. Have fun and don't hesitate to contact us at support@lemon.markets or in our Slack community if you have any questions.