Manage your trading portfolio with the lemon.markets brokerage API
Tags: api, programming, trading, algotrading
Published: 2021-12-21 18:55:21

An important part of a functional brokerage service is the possibility to conveniently monitor everything related to your portfolio. Therefore, in this blog post, I want to dive deeper into how to keep an overview of your portfolio items with the [lemon.markets](https://www.lemon.markets/) brokerage API.

---

[lemon.markets](https://www.lemon.markets/) was born out of the wish/need to have more flexibility in the way you manage your trading activities. The result of months of iteration with our beta users is an API that allows you to build your own brokerage experience at the stock market, customised to your individual use case. Check out our [documentation](https://docs.lemon.markets/) to learn more about the structure of our API and what you can build with it.

We offer different endpoints to, for instance, buy or sell stocks, retrieve historical market data or manage your account. However, in this blog post we we want to specifically deal with the `/portfolio` endpoint which allows you to conveniently monitor your (who would’ve guessed?) portfolio.

In general, your portfolio consists of different portfolio items that are the result of executed orders. This means that if your portfolio is empty and you place an order for 10 Tesla shares, once that order is executed (i.e. placed _and_ filled at the stock market) your portfolio consists of 10 shares of Tesla stock.

Let’s take a look at how you get that information through the lemon.markets API.

## Using the /portfolio endpoint
To access your portfolio, use the following URL:
```
https://paper-trading.lemon.markets/v1/portfolio/
```
Below, find an example code snippet in Python. Check out our [documentation](https://docs.lemon.markets/trading/working-with-portfolio-transactions) for additional code snippets in JavaScript.
``` python
import requests

request = requests.get("https://paper-trading.lemon.markets/v1/portfolio/", 
                       headers={"Authorization": "Bearer YOUR-API-KEY"})
print(request.json())
```
Making the request stated above will result in a response similar to this one:
``` json
{
  "time":"2021-11-21T19:34:45.071+00:00",
  "status": "ok",
  "results": [
    {
     "space_id": "sp_pyPFYssNNJyV4m8rxtK7LnfGwKLMk2njSv",
     "isin": "US19260Q1076",
     "isin_title": "COINBASE GLOBAL INC.",
     "quantity": 1,
     "buy_quantity": 1,
     "sell_quantity": 0,
     "buy_price_avg": 2965000,
     "buy_price_min": 2965000,
     "buy_price_max": 2965000,
     "buy_price_avg_historical": 2965000,
     "sell_price_min": null,
     "sell_price_max": null,
     "sell_price_avg_historical": null,
     "orders_total": 1,
     "sell_orders_total": 0,
     "buy_orders_total": 1
    },
    {
      "space_id": "sp_pyPFYssNNJyV4m8rxtK7LnfGwKLMk2njSv",
      ...
    }
  ]
}
```
The results part of the response is an array of objects. Each object represents a different portfolio item and you can retrieve a lot of interesting information from it. For instance, the `space_id` tells you which Space the portfolio item belongs to, `isin` is the International Security Identification Number through which an instrument can uniquely be identified. Additionally, you receive information on the current quantity of the instrument in your portfolio, how many shares you bought, how many you sold and at what price.

## Working with query parameters
While a general overview of all portfolio items is nice, you might want to narrow your search. That’s what query parameters are for. In the `/portfolio` endpoint, you can query for the `space_id` and the `isin`, which allows you to either only see portfolio items from a specific Space or only portfolio items for a specific instrument. Or both.

Using the query parameters is really easy, you simply add them to your request URL.

``` python
import requests

request = requests.get("https://paper-trading.lemon.markets/v1/portfolio/?isin=US88160R1014", 
                       headers={"Authorization": "Bearer YOUR-API-KEY"})
print(request.json())
```
This will result in only Tesla portfolio items being displayed. If you have multiple Spaces with which you traded Tesla stock, you will still retrieve multiple objects, e.g. Space 1 with 17 Tesla shares, Space 2 with 9 Tesla shares, and Space 3 with 2 Tesla shares. However, if you only hold the respective portfolio item in one of your Spaces, the API will only return a results array of length one.

Additionally, you can also enforce to only get one result by also specifying a `space_id` next to the `isin`. Simply add `&space_id={YOUR_SPACE_ID}` to the request URL displayed above. With that request, you will get the portfolio information of a specific instrument in a specific Space.

## And now: what to do with it?
The possibilities from here on are (almost) endless. You could build your own dashboard to display your portfolio using some cool charts, you could integrate the information in your own custom trading app or build an analysis tool that automatically buys or sells stock to rebalance your portfolio. Get creative!

---

We are really excited for you to try out our API and help shape a product that developers enjoy using. Make sure to sign up on our [website](https://www.lemon.markets/) and join our growing [Slack community](https://lemonmarketscommunity.slack.com/join/shared_invite/zt-uld4skdd-NRkts~S249bN8ixc0SMHqA#/shared-invite/email) where we discuss all things lemon.markets with more than 400 developers.

See you there,

the 🍋.markets team