Trading / Positions

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

Authorization
string
required

Set your Authorization header in the format "Authorization: Bearer YOUR-API-KEY"
(see the example in the code snippet on the right)

Query Parameters

isin
string
optional

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

limit
int
optional

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.

page
int
optional

This parameter is required to influence the Pagination. Use it to define the specific results page you wish to display.

Response

Response Parameters

isin
string

This is the International Securities Identification Number (ISIN) of the position

isin_title
string

This is the Title of the instrument

quantity
int

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

buy_price_avg
int

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€.

estimated_price_total
int

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€

estimated_price
int

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

Other Attributes

time
string

Timestamp of your request

status
string

Shows status "ok" when positions were successfully retrieved

mode
string

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

Pagination

previous
string

Pagination attribute: this is a URL of the previous page

next
string

Pagination attribute: this is a URL of the next page

total
int

Pagination attribute: this is the total number of results

page
int

Pagination attribute: this is the current page number

pages
int

Pagination attribute: this is the total number of pages

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

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

Authorization
string
required

Set your Authorization header in the format "Authorization: Bearer YOUR-API-KEY"
(see the example in the code snippet on the right)

Query Parameters

type
string
optional

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)
Read more ↘
limit
int
optional

Required for Pagination. Limit of displayed results on one page

page
int
optional

Required for Pagination. Results page you wish to display

Response

Response Parameters

id
string

This is the unique Identification Number for the statement

order_id
string

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

external_id
string

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

type
string

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)
Read more ↘
quantity
string

This is the quantity related to the position statement

isin
string

This is the ISIN of the Instrument that is affected in the statement

isin_title
string

This is the Title of the Instrument that is affected in the statement

date
string

This is the Date the statement occurs at (YYYY-MM-DD)

created_at
string

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

time
string

Timestamp of your request

status
string

Shows status "ok" when statements were successfully retrieved

mode
string

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

Pagination

previous
string

Pagination attribute: this is a URL of the previous page

next
string

Pagination attribute: this is a URL of the next page

total
int

Pagination attribute: this is the total number of results

page
int

Pagination attribute: this is the current page number

pages
int

Pagination attribute: this is the total number of pages

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

GETpositions/statements/
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())
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

Authorization
string
required

Set your Authorization header in the format "Authorization: Bearer YOUR-API-KEY"
(see the example in the code snippet on the right)

Query Parameters

isin
string
optional

Filter for a specific instrument in your positions

from
string
optional

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.

to
string
optional

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

sorting
string
optional

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

limit
int
optional

Required for Pagination. Limit of displayed results on one page

page
int
optional

Required for Pagination. Results page you wish to display

Response

Response Parameters

isin
string

This is the ISIN of the respective position

isin_title
string

This is the Title of the respective position

profit
int

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

loss
int

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

quantity_bought
int

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

quantity_sold
int

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

quantity_open
int

This shows the number of open position shares

opened_at
string

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

closed_at
string

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

fees
int

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

Other Attributes

time
string

Timestamp of your request

status
string

Shows status "ok" when statements were successfully retrieved

mode
string

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

Pagination

previous
string

Pagination attribute: this is a URL of the previous page

next
string

Pagination attribute: this is a URL of the next page

total
int

Pagination attribute: this is the total number of results

page
int

Pagination attribute: this is the current page number

pages
int

Pagination attribute: this is the total number of pages

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

GETpositions/performance/
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())
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