Quickstart

In this Quickstart guide, we will walk you through the simple steps you need to take to buy your first stock with the lemon.markets API in less than 5 minutes. You will learn how to create your first API Key, how to uniquely identify the stock you are interested in and how to buy it with one API request. Let's get started.

5 Minutes is too much for you? Use our Postman Workspace instead!

We are trying to make this Quickstart guide concise and efficient for you. However, if you cannot wait any longer, please use our Postman workspace to try out all endpoints and see their responses.

Signing up

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.

Paper Trading

The lemon.markets API offers you a Paper Trading environment, where you can test out all your ideas risk-free.

The URL for the Paper Trading Environment is:

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

Request Body

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

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

After you sign up to lemon.markets, we deposit you 100,000€ Paper Money and you can get started using the Paper Trading Environment straight away. To use the Live Trading Environment, you must complete the onboarding process with the lemon.markets mobile App. Check out this page for more information.

For the rest of this Quickstart guide, we will refer to the Paper Trading Environment. If you are interested in Live Trading, simply exchange the request base URL 😉

Getting Access

After activating your account, you are almost ready to start using the lemon.markets API. However, one step is missing: as most requests require authentication, you need to create an API Key which you can use for your requests.

To create a new API Key, log into your Dashboard and click on "Create Key". You can create an API Key for the Paper and the Money environment (provided you have upgrade to Live Trading).

In the Modal, you can then specify the name of you API Key and how long you want it to be valid. Ater you click on "Create Key", the API Key is added to your Dashboard. To use it, simply click on the "copy" symbol on the right side of the table.

Finding a Stock

Any security that is tradable on a stock exchange can be uniquely identified through its International Securities Identification Number (ISIN). The ISIN is also crucial in the context of the lemon.markets API, as you can use it to specify the security (e.g. a stock or ETF) you want to buy. If you already know the ISIN of your preferred stock, you can skip this next part. If you are unsure, you can find the ISIN (and other) information using the following endpoint:

https://data.lemon.markets/v1/instruments

You can use this endpoint to search for a specific stock using the ?search query parameter.

GET /instruments

If you were interested in finding the Coinbase stock, you could simply call the /instruments endpoint and attach the query parameter ?search, followed by your specific search term, in this case Coinbase. Simply copy the code snippet on the right, insert the API Key you just created in the request header and the lemon.markets API should return a relevant response for you.

Let's take a closer look at the response:

Response

The API returns a number of things that are relevant for us going forward. First, this is the ISIN, which we need to specify which security we want to buy. The response also contains additonal information like the exact title, the type of instrument (in this case a stock), or the stock exchange (venue) the stock is traded at. To buy a specific stock, we need to use the ISIN, as you will see next.

GET/instruments?search=Coinbase

1import requests
2import json
3
4market_data_key = 'YOUR-MARKET-DATA-KEY'
5request = requests.get("https://data.lemon.markets/v1/instruments?search=Coinbase",
6          headers={"Authorization": f"Bearer {market_data_key}"})
7print(request.json())

Response

1{
2  "time": "2022-02-14T20:44:03.759+00:00",
3  "results":
4  [
5    {
6      "isin": "US19260Q1076",
7      "wkn": "A2QP7J",
8      "name": "COINBASE GLB.CL.A -,00001",
9      "title": "COINBASE GLOBAL INC",
10      "symbol": "1QZ",
11      "type": "stock",
12      "venues":
13      [
14        {
15          "name": "Börse München - Gettex",
16          "title": "Gettex",
17          "mic": "XMUN",
18          "is_open": true,
19          "tradable": true,
20          "currency": "EUR"
21        }
22      ]
23    }
24  ],
25  "previous": null,
26  "next": null,
27  "total": 1,
28  "page": 1,
29  "pages": 1
30}
31

Placing your first Order

Now that you know the ISIN of the stock you want to buy, you are almost ready to actually purchase it. In order to buy a stock with the lemon.markets API, you need to create a POST request against the following URL:

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

This POST request will create an order and requires you to specify the type of data you want to send in its request body. So basically, all important aspects of your order are sent together with the POST request body.

POST /orders

As with most API requests, you need to authenticate yourself here as well. Same as before, add your API Key to the request header, as shown in the code snippet on the right.
For your POST request, there are 5 required request body parameters that you need to specify for your order to go through. Let's go through them one by one.

Request Body Parameters

Here, you can add your desired ISIN that your search returned earlier. This is crucial to specificy the exact stock you are interested in buying.

With this attribute, you can specify for how long you want your order to be valid. You can either set an ISO String date (YYYY-MM-DD) or define a specific duration.

For this, you can use the format "pxd" (e.g. "p7d" if you want your order to be valid for 7 days). Maximum expiration date in both cases is 30 days in the future.

In the case of a market order (which we place in this example) the expires_at* parameter is optional, the default value is the end of the same day.

When limit_price and/or stop_price are set, the expires_at parameter is required.

Response

If the request was successful, the API returns "status": "ok". Congratulations, you just placed your first order with the lemon.markets API. Log into your Dashboard to get an overview of all your orders.

But now, let's take a closer look at the response: it contains specific information on your order like an overview of all order attributes or information on order costs. If you are interested in finding out more about the POST /orders response, check out the order page directly.

POST/orders

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": "2021-11-25",
9              "side": "buy",
10              "quantity": 1,
11              "venue": "XMUN",
12            }),
13          headers={"Authorization": f"Bearer {paper_trading_key}"})
14print(request.json())

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": null,
35    "limit_price": null,
36    "venue": "xmun",
37    "estimated_price": 66140000,
38    "notes": "I want to attach a note to this order"
39  }
40}
41

Activating an Order

Buying an instrument with the lemon.markets API is always a two-step process. After you submitted an order (step 1) you need to activate the order to actually route it to the stock exchange (step 2). 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 in the Paper Money Environment, you have two options:

Manually activate the Order in the Dashboard
Use the endpoint /orders/{order_id}/activate.

Activate an Order in the Dashboard

After you placed your order, go to your Dashboard and scroll to the Orders table. At the top of the table you should see that the order you just placed has the status "inactive". If you scroll to the right side of the table, you will see a blue "Activate" button. If you click it, you are greeted with a modal similar to this one:

Use the endpoint `/orders/{order_id}/activate`

If you are interested in building your own 2FA experience, you can alternatively use the following endpoint to activate your order:

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

POST /orders/{order_id}/activate

To activate your order via API request, grab the order ID from the POST /orders response and paste it into your request URL. Additionally, specify your PIN in the request body. If you want to activate a paper money order you can use any random 4-digit PIN or send the request without request body. For a live trading order, use the PIN that you set during your onboarding.

Response

See the example response on the right. If everything went well, the API should return "status": "ok".

POST/orders/{order_id}/activate

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

Response

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

Find detailed information about all things related to orders in the docs section Orders. There, you can also learn how to activate live trading orders with the lemon.markets mobile app.

See your Positions

After you placed a few orders, you might be interested in getting an overview of everything that happened already. Using the /positions endpoint, you can get in-depth information on all your positions, whereby, in general, a position is the result of an executed order.

To request your positions, we are placing another GET request and use the following request URL:

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

The API will return all your positions, including detailed information on each one. Let's take a closer look at the request and response.

GET /positions

Specify your request as follows:

As before, make sure to put your API Key into your request header to authenticate yourself. You can then make a simple GET request, as in the example on the right. You can additionally attach a query paramater to specify your request.

Using the ?isin query parameter, you can filter for a specific instrument in your positions. In the code snippet on the right, we are filtering for Coinbase.

Response

The response contains one JSON object for each instrument. In the response on the right, you can see that we hold 2 shares of Coinbase. Additionally, the average buy-in price is returned, as well as the current estimated price so you have an overview of the current valuation of your position.

GET/positions?isin=US19260Q1076

1import requests
2import json
3
4paper_trading_key = 'YOUR-PAPER-TRADING-KEY'
5request = requests.get("https://paper-trading.lemon.markets/v1/positions?isin=US19260Q1076",
6          headers={"Authorization": f"Bearer {paper_trading_key}"})
7print(request.json())

Response

1{
2  "time":"2021-11-21T19:34:45.071+00:00",
3  "status": "ok",
4  "mode":"paper",
5  "results": [
6    {
7      "isin": "US19260Q1076",
8      "isin_title": "COINBASE GLOBAL INC.",
9      "quantity": 2,
10      "buy_price_avg": 2965000,
11      "estimated_price_total": 5800000,
12      "estimated_price": 2900000
13    },
14    {
15      "isin": "US19260Q1076",
16      ...
17    }
18  ],
19  "previous": "https://paper-trading.lemon.markets/v1/positions?limit=10&page=1", 
20  "next": "https://paper-trading.lemon.markets/v1/positions?limit=10&page=3", 
21  "total": 33, 
22  "page": 2, 
23  "pages": 4
24}

Conclusion and next steps

We hope that this section gave you a quick start. If you are interested in more detailed explanations, dive right into some of our other resources:

Market Data

In this Quickstart Guide we presented you the steps you need to take to place an order in less than 5 minutes. However, if you are interested in retrieving historical and live market data, you can do that with lemon.markets as well. Please check out the Market Data and Live Streaming APIs for more information.

Blog

In our blog we regularly post articles about specific projects and background information on the stock market and/or algorithmic trading. If you are looking for inspiration for your own trading project: go check it out.

Slack Community

In our Slack community we are discussing all things lemon.markets with more than 500 developers. Feel free to join if you have a question, want to discuss a feature you would find valuable, want to get in touch with other community members or just want to see what's going on 😎