Positions

We believe that it is important to be able to keep a convenient overview over all your positions that affect your portfolio. In general, an executed order triggers a portfolio change, whereby a buy order adds something to and a sell order removes something from your positions.

Positions

After you placed a few orders, you might be interested in seeing how your Positions look like. Using the /positions endpoint, you can get in-depth information on all your positions.

GET /positions

To list all your Paper Trading Positions, use the following request URL:

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

To list all your Live Trading Positions, use the following request URL:

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

Request

To retrieve your positions, 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

Use this parameter to filter for a specific Instrument in your positions using the instrument's ISIN

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 International Securities Identification Number (ISIN) of the position

This is the Title of the instrument

This is the number of positions you currently hold for the respective Instrument

This is the average buy-in price of the respective position. If you buy one share for 100€ and a second one for 110€, the average buy-in price would be 105€.

This is the current position valuation to the market trading price. So, if you own 3 shares of stock XYZ, and the current market trading price for XYZ is 100€, this attribute would return 300€

This is the current market trading price for the respective position.

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

Timestamp of your request

Shows status "ok" when positions were successfully retrieved

This is the environment the request was placed in: "paper" or "money"

Check our Error Handling Page for specific information on error types.

GET/positions

1import requests
2import json
3
4paper_trading_key = 'YOUR-PAPER-TRADING-KEY'
5request = requests.get("https://paper-trading.lemon.markets/v1/positions",
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}
25
26

Statements

We offer one endpoint that gives you an overview of all change events happening to your positions. For example, this can happen when you buy or sell a position, import shares from an external brokerage account, or when a stock is split. All of these events results in a so-called "Statement", which gives you detailed insights into the change event.

GET /positions/statements

To list all your Paper Trading Statements, use the following request URL:

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

To list all your Live Trading Statements, use the following request URL:

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

Request

To retrieve your position statements, 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

Filter for a specific type of Statement. Choose one of the following: order_buy | order_sell | split | import | snx

order_buy: Statement related to a buy order
order_sell: Statement related to a sell order
split: Statement related to an instrument split
import: Statement related to an instrument exported from an external source
snx: Snapshot for each day. Gives you an aggregated overview of each instrument separately (on days with changes)

Response

Response Parameters

This is the unique Identification Number for the statement

This is the unique Identification Number for the related order (if type = order_buy or order_sell, otherwise null)

If you imported a position from an external source, we provide the external identification number here

This is the type of statement that tells you about the type of change that happened to your position : order_buy | order_sell | split | import | snx

order_buy: Statement related to a buy order
order_sell: Statement related to a sell order
split: Statement related to an instrument split
import: Statement related to an instrument exported from an external source
snx: Snapshot for each day. Gives you an aggregated overview of each instrument separately (on days with changes)

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

Timestamp of your request

Shows status "ok" when statements were successfully retrieved

This is the environment the request was placed in: "paper" or "money"

Check our Error Handling Page for specific information on error types.

GET/positions/statements

1import requests
2import json
3
4paper_trading_key = 'YOUR-PAPER-TRADING-KEY'
5request = requests.get("https://paper-trading.lemon.markets/v1/positions/statements",
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":"money",
5  "results": [
6    {
7      "id": "hs_pyHJLHHNBHbK943xcyYdB8l4scC0dJs2xW",
8      "order_id": "ord_pyNBHJJ66Mp9k3YHztpBb1m984WRGCYq5D",
9      "external_id": null,
10      "type": "order_buy",
11      "quantity": 1,
12      "isin": "US19260Q1076",
13      "isin_title": "COINBASE GLOBAL INC.",
14      "date": "2021-12-10",
15      "created_at": "2021-12-10T07:57:12.628+00:00"
16    },
17    {
18      "id": "hs_pyHJLBVCBHbK943xcyYdB8l4scC0dJs2xW",
19      ...
20    }
21  ],
22  "previous": "https://paper-trading.lemon.markets/v1/positions/statements?limit=10&page=1", 
23  "next": "https://paper-trading.lemon.markets/v1/positions/statements?limit=10&page=3", 
24  "total": 33, 
25  "page": 2, 
26  "pages": 4
27}
28
29

Performance

We offer one endpoint that gives you an overview of your position performances. Using this endpoint, you can retrieve when positions were opened and closed, potential profits/losses, or related fees for position orders.

GET /positions/performance

To list all performances from Paper Environment positions, use the following request URL:

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

To list all performances from Live Trading Environment positions, use the following request URL:

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

Request

To retrieve your position performances, 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

Filter for a specific instrument in your positions

Specify an ISO date string (YYYY-MM-DD) to get position performances from a specific date on. If "from" is not specified, the API returns the last 30 days by default.

Specify an ISO date string (YYYY-MM-DD) to get position performances until specific date on.

Use "asc" to sort your position performances in ascending order and "desc" to sort your position performances in descending order.

Required for Pagination. Limit of displayed results on one page

Required for Pagination. Results page you wish to display

Response

Response Parameters

This is the ISIN of the respective position

This is the Title of the respective position

This shows a profit when all or parts of the respective position were sold for more than they were bought for. Otherwise 0.

This shows a loss when all or parts of the respective position were sold for less than they were bought for. Otherwise 0.

This shows how many position shares were bought over specific time period

This shows how many position shares were sold over specific time period

This shows the number of open position shares

This show the specific timestamp for when the position was opened (first share(s) were bought)

This show the specific timestamp for when the position was closed (last share(s) were sold)

This shows the amount of fees for orders related to the respective position

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

Timestamp of your request

Shows status "ok" when statements were successfully retrieved

This is the environment the request was placed in: "paper" or "money"

Check our Error Handling Page for specific information on error types.

GET/positions/performance

1import requests
2import json
3
4paper_trading_key = 'YOUR-PAPER-TRADING-KEY'
5request = requests.get("https://paper-trading.lemon.markets/v1/positions/performance",
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":"money",
5  "results": [
6    {
7      "isin": "US19260Q1076",
8      "isin_title": "COINBASE GLOBAL INC.",
9      "profit": 89400,
10      "loss": 0,
11      "quantity_bought": 1,
12      "quantity_sold": 1,
13      "quantity_open": 0,
14      "opened_at": "2022-02-02T16:20:30.618+00:00",
15      "closed_at": "2022-02-03T12:32:00.762+00:00",
16      "fees": 40000
17    },
18    {
19      "isin": "US0090661010",
20      ...
21    }
22  ],
23  "previous": "https://trading.lemon.markets/v1/positions/performance?limit=10&page=1", 
24  "next": "https://trading.lemon.markets/v1/positions/performance?limit=10&page=3", 
25  "total": 37, 
26  "page": 2, 
27  "pages": 4
28}
29
30