Placing your first order with the lemon.markets Trading API
Tags: trading, programming, api, algotrading
Published: 2021-12-21 18:47:22

[lemon.markets](https://lemon.markets) offers a simple API that allows you to create your own **brokerage experience** at the stock market. An important part of that is the possibility to **place orders with one simple API call**. In this blog post, I will walk you through the steps you need to take to **place and activate an order** with the **lemon.markets Trading API**. Ready, set, go 🏃👩‍💻

## Getting access
Start by signing up on our [dashboard](https://dashboard.lemon.markets/). After you verified your account, you can log in and use the first API Key and [Space](https://medium.com/lemon-markets/introducing-lemon-markets-spaces-890d3c1ea6e) that we already created for you by default. After that, you are ready to place your first order.

## Place your first order
To place an order with lemon.markets, you need to address the trading API by making a POST request against the base URL and add /orders/ to it:

To place an order with lemon.markets, you need to address the trading API by making a POST request against the base URL and add /orders/ to it:
```
https://paper-trading.lemon.markets/v1/orders/
```
Make sure to specify your order through your request body. 

Some of the parameters in there are required (`isin` to specify the instrument you want to buy, `expires_at` to define when the order expires, `side` to either buy or sell, `quantity` to specify how many shares you wish to buy, `venue` to address a specific trading venue, and `space_id` to place the order for a specific space). 

Others are optional (`stop_price` to place a stop market order, `limit_price` for a limit order, or both for a stop limit order, or `notes` if you want to add some notes with your order so you later know why you placed it in the first place). 

See an example request in Python below. You can check out our [documentation](https://docs.lemon.markets/) for additional code snippets in JavaScript and more detailed explanations on different request parameters.

```python
import requests
import json

request = requests.post("https://paper-trading.lemon.markets/v1/orders/",
          data=json.dumps({
              "isin": "US19260Q1076",
              "expires_at": "2021-11-25",
              "side": "buy",
              "stop_price": 5000000,
              "limit_price": 5300000,
              "quantity": 1,
              "venue": "XMUN",
              "space_id": "123456789",
              "notes": "I want to attach a note to this order"
            }), headers={"Authorization": "Bearer YOUR-API-KEY"})
print(request.json())
```
<figcaption>Place your order</figcaption>

## Dealing with the API Response
When you successfully placed your order, the API responds with a
```
200 
"status": "ok"
```
and outputs some additional response elements. For instance, you learn about the `estimated_price` or the regulatory information associated to your order. And you receive the `order_id`, which is crucial for the next (and final) step before your order can get executed.

## Activating an Order
Before we route your order to a trading venue, you first need to activate it. You can do this through the following endpoint:
```
https://paper-trading.lemon.markets/v1/orders/{order_id}/activate/
```

See now why it is crucial that the POST request against the /orders/ endpoint returns the `order_id`? Using the ID, we can activate the order through:
``` python
import requests
import json

request = requests.post("https://paper-trading.lemon.markets/v1/orders/{order_id}/activate/",
            headers={"Authorization": "Bearer YOUR-API-KEY"})
print(request.json())
```
<figcaption>Activate an order through its order_id
</figcaption>

On success, the order is activated and routed to the specified trading venue. You can now sit back and relax — your work here is done (for now).

## Retrieving your Orders
You can retrieve all your orders by posting a GET request against the `/orders` endpoint:
```
https://paper-trading.lemon.markets/v1/orders/
```
To specify your request, you can add **query parameters** to your request:

- `space_id`: filter for orders from a specific space
- `from` & `to`: you can define a time range from which you want to retrieve orders
- `isin`: add this query parameter to only see orders related to a specific isin
- `side`: query parameter to see only buy or sell orders
- `status`: filter for order status, e.g. inactive or executed
- `type`: filter for different types of orders: market, stop, limit, stop_limit

See the example request below to learn how to use the query parameters in your request. In the example, we only want to see Tesla buy orders, therefore using the `isin` and `side` query parameters:

``` python
import requests

request = requests.get("https://paper-trading.lemon.markets/v1/orders/?isin=US88160R1014&&side=buy", 
                       headers={"Authorization": "Bearer YOUR-API-KEY"})
print(request.json())
```

## Ideas for Inspiration
You now know how to place an order with the lemon.markets Trading API. Now: what to do with it? There are plenty of use cases. Think of the order placement as the final step in your awesome trading project. You have an automated trading strategies that buys stocks based on predefined criteria? Great, the order endpoint is triggered when a certain threshold in your algo is crossed. You built your own trading app to buy and sell stocks? Great, whenever you click the buy/sell button in your application, you will need the POST /orders/ endpoint. What are your additional ideas for how to use the `/orders` endpoint? Let us know 🙂

I hope you got a good understanding of one of our most crucial API endpoints. If you have any questions or want to get in touch with other liked-minded developers: join our growing [Slack community](https://lemonmarketscommunity.slack.com/join/shared_invite/zt-uld4skdd-NRkts~S249bN8ixc0SMHqA#/shared-invite/email) and discuss your newest trading project idea. And for more inspiration: check out our [other blog articles](https://medium.com/lemon-markets).

Excited to see what you are building with us 😍