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:
To list all your Live Trading Positions, use the following request URL:
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.
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"
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
Check our Error Handling Page for specific information on error types.
1import requests
2import json
3
4request = requests.get("https://paper-trading.lemon.markets/v1/positions/",
5 headers={"Authorization": "Bearer YOUR-API-KEY"})
6print(request.json())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:
To list all your Live Trading Statements, use the following request URL:
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)
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 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)
This is the quantity related to the position statement
This is the ISIN of the Instrument that is affected in the statement
This is the Title of the Instrument that is affected in the statement
This is the Date the statement occurs at (YYYY-MM-DD)
Timestamp for when the statement is processed by us internally. It can be the case that we receive data 1-3 days later. So, for example when a position change occurs on a Friday afternoon, we only receive the data on Monday morning. Therefore, date would then be YYYY-MM-DD of the Friday, while created_at is a timestamp from Monday morning.
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"
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
Check our Error Handling Page for specific information on error types.
1import requests
2import json
3
4request = requests.get("https://paper-trading.lemon.markets/v1/positions/statements/",
5 headers={"Authorization": "Bearer YOUR-API-KEY"})
6print(request.json())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:
To list all performances from Live Trading Environment positions, use the following request URL:
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
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"
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
Check our Error Handling Page for specific information on error types.
1import requests
2import json
3
4request = requests.get("https://paper-trading.lemon.markets/v1/positions/performance/",
5 headers={"Authorization": "Bearer YOUR-API-KEY"})
6print(request.json())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