Trading / Account

Account

Get your Account information

In your account, all important information about yourself are stored. Based on the information in your account, you can, among others, deposit money into your brokerage account, withdraw money to your reference account or access all your tax-related information. Find more details on all account endpoints below.

GET /account

To retrieve all your account information use the following request URLs:

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

or

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

Request

To retrieve your account information, 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)

Response

Response Parameters

account_id
string

Unique Identification number for your account

firstname
string

Your first name

lastname
string

Your last name

iban_brokerage
string

IBAN of the brokerage account at our partner bank. This is the IBAN you can transfer money from your referrence account to.

iban_origin
string

IBAN of the reference account. You define your reference account as part of the live trading onboarding. You can use your reference account to transfer money to your brokerage acount. You can also withdraw money from your brokerage account to your reference account.

balance
int

This is your account balance - the amount of money you have available in your brokerage account. The balance calculates as follows:

(Your end-of-day balance from the day before) + (amount_sold_intraday) - (amount_bought_intraday) - (amount_open_withdrawals).

Read more ↘
cash_to_invest
int

This number shows you how much cash you have left to invest. The cash_to_invest calculates as follows:

(balance) - (amount_open_orders)

Read more ↘
cash_to_withdraw
int

This number shows you how much cash you have in your account to withdraw to your reference account.

cash_to_withdraw is calculated as follows:

(Your end-of-day balance from the day before) - (amount_bought_intraday) - (amount_open_withdrawals) - (amount_open_orders).

Read more ↘
amount_bought_intraday
int

This is the intraday buy order amount.
For example, if you bought 2 shares for 100€ each that day, the amount_bought_intraday would be 200€ (the API would return 2000000 in that case, see our numbers page for more information).

amount_sold_intraday
int

This is the intraday sell order amount.
For example, if you sold 3 shares for 50€ each that day, the amount_sold_intraday would be 150€ (the API would return 1500000 in that case, see our numbers page for more information).

Read more ↘
amount_open_orders
int

This is the intraday amount of open orders.
If you place an order that has amount X and its status is open, the amount_open_orders would be the order amount (+ the sum of all other open intraday orders).

amount_open_withdrawals
int

This is the intraday amount of withdrawals.
For example, if you withdraw 500€ to your reference account, amount_open_withdrawals would return 5000000 (see our numbers page for detailed information on the numbers format in the Trading API).

amount_estimate_taxes
int

This is the amount of estimated taxes (25%) for your intraday sell orders.
For example, if you made a profit of 100€ from your intraday sell orders, the API would return 250000 (see our numbers page for detailed information on the numbers format in the Trading API).

Other Attributes

time
string

Timestamp of your API request

status
string

API returns "ok" when account was successfully retrieved.

mode
string

Environment the request was placed in: "paper" or "money"

created_at
string

Timestamp for when you created your account

email
string

Your specified email address

phone
string

Your specified phone number

address
string

Your specified address

billing_address
string

The billing address you provided for your account

billing_email
string

The billing email address you provided for your account

billing_name
string

The billing name you provided for your account

billing_vat
string

The billing VAT number you provided for your account

mode
string

The mode your account is currently on - "paper" or "money"

deposit_id
string

Identification Number of your securities account

client_id
string

The internal client identification number related to your account

account_number
string

The account reference number

bank_name_origin
string

Bank name your reference account is located at

approved_at
int

Timestamp of live trading account approval

trading_plan
string

We offer different subscription plans for trading with lemon.markets. This endpoint tells you which plan you are currently on - go, investor, trader, or b2b.

data_plan
string

We offer different subscription plans for retrieving market data with lemon.markets. This endpoint tells you which plan you are currently on - go, investor, trader, or b2b.

tax_allowance
int

Your tax tax allowance - between 0 and 801 €, as specified in your onboarding process

tax_allowance_start
string

Relevant start date for your tax allowance (usually 01/01/ of respective year)

tax_allowance_end
string

Relevant end date for your tax allowance (usually 31/12/ of respective year)

GET/account
1import requests
2import json
3
4paper_trading_key = 'YOUR-PAPER-TRADING-KEY'
5request = requests.get("https://paper-trading.lemon.markets/v1/account",
6          headers={"Authorization": f"Bearer {paper_trading_key}"})
7print(request.json())
Response
1{
2  "time": "2021-11-22T15:37:56.520+00:00",
3  "status": "ok",
4  "mode":"paper",
5  "results": {
6    "created_at": "2021-10-12T10:29:49.769+00:00",
7    "account_id": "acc_pyNQNll99hQbXMCS0dRzHyKQCRKYHpy3zg",
8    "firstname": "Michael",
9    "lastname": "Burry",
10    "email": "m_burry@tradingapi.com",
11    "phone": "+491637876521",
12    "address": "Ritterstraße 2A 10969 Berlin",
13    "billing_address": "Ritterstraße 2A 10969 Berlin",
14    "billing_email": "m_burry@tradingapi.com",
15    "billing_name": "Michael Burry",
16    "billing_vat": "DE999999999",
17    "mode": "paper",
18    "deposit_id": "K2057263187",
19    "client_id": "2057263",
20    "account_number": "2057263187",
21    "iban_brokerage": "DE12345678902057263",
22    "iban_origin": "DE123456789012345",
23    "bank_name_origin": "Test Bank",
24    "balance": 100000000,
25    "cash_to_invest": 80000000,
26    "cash_to_withdraw": 20000000,
27    "amount_bought_intraday": 0,
28    "amount_sold_intraday": 0,
29    "amount_open_orders": 0,
30    "amount_open_withdrawals": 1475200,
31    "amount_estimate_taxes": 0,
32    "approved_at": "2021-11-19T07:40:12.563+00:00",
33    "trading_plan": "investor",
34    "data_plan": "investor",
35    "tax_allowance": 8010000,
36    "tax_allowance_start": "2021-01-01",
37    "tax_allowance_end": "2021-01-01"
38  }
39}
40  

Withdrawals

Withdrawals are payments that you send from your brokerage account to your reference account. You can manage all withdrawals with two simple API endpoints.

POST /account/withdrawals

To withdraw money to your reference account, use the following request URLs:

https://paper-trading.lemon.markets/v1/account/withdrawals

or

https://trading.lemon.markets/v1/account/withdrawals

Withdrawing Paper Money

One of our core principles is to have an identical structure for the Real Money and Paper Money API. Therefore, this endpoint also works in Paper Money (does not throw an error message), but obviously does not transfer any actual money to your reference account. 😉

Request

To make a withdrawal to your reference account, 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)

Request Body Parameters


Request Body

You can send your request using the following content-types:

  • application/json
  • application/x-www-form-urlencoded

amount
int
required

Using this request body parameter, you can specify the amount you wish to withdraw. Specify the amount in the format Int * 10000 (e.g., 1000000 to withdraw 100 €).
Please see here for more information on the numbers format in the Trading API.

pin
int
required

This is the personal verification PIN you set during the onboarding.

idempotency
string
optional

You can set your own unique idempotency key to prevent duplicate operations. Subsequent requests with the same idempotency key will then not go through and throw an error message. This means you cannot make the same withdrawal twice.

Response

Response Parameters

time
string

Timestamp of your request

status
string

API returns "ok" when money was successfully withdrawn.

mode
string

Environment the request was placed in: "paper" or "money"

POST/account/withdrawals
1import requests
2import json
3
4paper_trading_key = 'YOUR-PAPER-TRADING-KEY'
5request = requests.post("https://paper-trading.lemon.markets/v1/account/withdrawals",
6          data=json.dumps({
7               "amount": 5000000,
8               "pin": 1234,
9            }),
10          headers={"Authorization": f"Bearer {paper_trading_key}"})
11print(request.json())
Response
1{
2  "time": "2021-11-22T15:37:56.520+00:00",
3  "mode":"paper",
4  "status": "ok"
5}
6  

GET /account/withdrawals

You can retrieve a list of all your executed withdrawals. Use the following request URLs to do so:

https://paper-trading.lemon.markets/v1/account/withdrawals

or

https://trading.lemon.markets/v1/account/withdrawals

Request

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

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

id
string

A unique Identification Number of your withdrawal

amount
string

The amount that you specified for your withdrawal

created_at
string

Timestamp at which you created the withdrawal

date
string

Timestamp at which the withdrawal was processed by our partner bank

idempotency
string

Your own unique idempotency key that you specified in your POST request to prevent duplicate withdrawals.

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

Other Attributes

time
string

Timestamp of your response

status
string

Shows status "ok" when withdrawals were successfully retrieved

mode
string

Environment the request was placed in: "paper" or "money"

GET/account/withdrawals
1import requests
2import json
3
4paper_trading_key = 'YOUR-PAPER-TRADING-KEY'
5request = requests.get("https://paper-trading.lemon.markets/v1/account/withdrawals",
6          headers={"Authorization": f"Bearer {paper_trading_key}"})
7print(request.json())
Response
1{
2  "time": "2021-12-15T11:21:21.023+00:00",
3  "status": "ok",
4  "mode":"paper",
5  "results": [
6    {
7      "id": "wtd_pyQTPbbLLMNBQTM0mzkK7Ygb8kH60Ff10X",
8      "amount": 1000000,
9      "created_at": "2021-12-15T11:21:05.853+00:00",
10      "date": "2021-12-15T25:12:02.765+00:00",
11      "idempotency": "1234abcd"
12    },
13    {
14      ...
15    }
16  ],
17  "previous": "https://paper-trading.lemon.markets/v1/account/withdrawals?limit=20&page=1",
18  "next": "https://paper-trading.lemon.markets/v1/account/withdrawals?limit=2&page=3",
19  "total": 80,
20  "page": 2,
21  "pages": 4
22}
23  

Bank Statements

Through our /bankstatements endpoint you can conveniently retrieve all activities on your brokerage account. The endpoint returns each bank statement in a separate object. A bank statement can be, for example, when you transferred money from/into your reference account, bought or sold a stock or when you got paid a dividend. Additionally, you always get an end of day balance that informs you about your account balance. Find out how to use the endpoint below.

GET /account/bankstatements

Per default, the API returns a list of objects containing all activities from your last “active day” (in the paper money environment) and all activities from the last working day (in the real money environment), where, by default, an end of day balance is created for you. Using query parameters "from" and "to", you can retrieve bank statements for a custom set period.

https://paper-trading.lemon.markets/v1/account/bankstatements

or

https://trading.lemon.markets/v1/account/bankstatements

Request

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 different types of bank statements: pay_in | pay_out | order_buy | order_sell | eod_balance | dividend |tax_refunded

  • pay_in: Statement related to new money entering your brokerage account
  • pay_out: Statement related to a withdrawal to your reference account
  • order_buy: Statement related to a buy order
  • order_sell: Statement related to a sell order
  • eod_balance: Your end-of-day balance
  • dividend: Statement related to a paid dividend for one of your positions
  • tax_refunded: Statement related to tax refunds
Read more ↘
from
string
optional

Filter for bank statements after a specific date. Format: "YYYY-MM-DD". If you set from=beginning, you can conveniently retrieve all bank statements since your account opening.

to
string
optional

Filter for bank statements until a specific date. Format: "YYYY-MM-DD".

sorting
string
optional

Use asc_ to sort your bank statements in ascending order (oldest ones first), or desc to sort your bank statements in descending order (newest ones first).

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

id
string

Unique Identification Number of your bank statement

account_id
string

Unique Identification Number of the account the bank statement is related to

type
string

Type of bank statement: pay_in | pay_out | order_buy | order_sell | eod_balance | dividend | tax_refunded

  • pay_in: Statement related to new money entering your brokerage account
  • pay_out: Statement related to a withdrawal to your reference account
  • order_buy: Statement related to a buy order
  • order_sell: Statement related to a sell order
  • eod_balance: Your end-of-day balance
  • dividend: Statement related to a paid dividend for one of your positions
  • tax_refunded: Statement related to tax refunds
Read more ↘
date
string

The date that the bank statement relates to (YYYY-MM-DD)

amount
int

The amount associated with the bank statement

isin
string

The International Securities Identification Number (ISIN) related to your bank statement. Only for type order_buy and order_sell, otherwise null

isin_title
string

The title of the International Securities Identification Number (ISIN) related to your bank statement. Only for type order_buy and order_sell, otherwise null

created_at
string

The timestamp the bank statement was created internally. This can be different to the date, e.g., when there is a weekend in between.

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

Other Attributes

time
string

Timestamp of your response

status
string

Shows status "ok" when withdrawals were successfully retrieved

mode
string

Environment the request was placed in: "paper" or "money"

GET/account/bankstatements
1import requests
2import json
3
4paper_trading_key = 'YOUR-PAPER-TRADING-KEY'
5request = requests.get("https://paper-trading.lemon.markets/v1/account/bankstatements",
6          headers={"Authorization": f"Bearer {paper_trading_key}"})
7print(request.json())
Response
1{
2  "time": "2021-11-22T15:41:04.028+00:00",
3  "status": "ok",
4  "mode": "paper",
5  "results": [
6    {
7      "id": "bst_pyQKKTTSS0Q2drg2J7yRhTwBkMPd1JgZzZ",
8      "account_id": "acc_pyNQNll99hQbXMCS0dRzHyKQCRKYHpy3zg",
9      "type": "order_buy",
10      "date": "2021-12-16",
11      "amount": 100000,
12      "isin": "US19260Q1076",
13      "isin_title": "COINBASE GLOBAL INC.",
14      "created_at": "2021-12-17T01:37:03.362+00:00"
15    },
16    {
17      ...
18    }
19  ],
20  "previous": "https://paper-trading.lemon.markets/v1/account/bankstatements?limit=20&page=1",
21  "next": "https://paper-trading.lemon.markets/v1/account/bankstatements?limit=2&page=3",
22  "total": 80,
23  "page": 2,
24  "pages": 4
25}
26  

Get Documents

We provide the possibility to retrieve different documents related to your account conveniently via API.

GET /account/documents

Use these endpoints to retrieve your available documents and receive them via API response:

https://paper-trading.lemon.markets/v1/account/documents

or

https://trading.lemon.markets/v1/account/documents

Request

To retrieve a list of your documents, 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)

Response

Response Parameters

time
string

Timestamp of request

mode
string

Environment the request was placed in: "paper" or "money"

status
string

API returns "ok" when documents were successfully retrieved

id
string

The unique Identification Number for the document

name
string

The name of the Document

created_at
string

Timestamp at which the Document was created internally

category
string

The Document Category

link
string

A Link to download a Document PDF

viewed_first_at
string

Timestamp at which the Document was first viewed (downloaded)

viewed_last_at
string

Timestamp at which the Document was last viewed (downloaded)

GET/account/documents
1import requests
2import json
3
4paper_trading_key = 'YOUR-PAPER-TRADING-KEY'
5request = requests.get("https://paper-trading.lemon.markets/v1/account/documents",
6          headers={"Authorization": f"Bearer {paper_trading_key}"})
7print(request.json())
Response
1{
2  "time": "2021-11-22T15:41:04.028+00:00",
3  "mode":"paper",
4  "status": "ok",
5  "results": [
6    {
7      "id": "doc_pyNjNcc77ht3T3lH8dJa5fD8jhj2JHJ1xX",
8      "name": "account_opening.pdf",
9      "created_at": "2021-10-19T14:58:52.813Z",
10      "category": "kyc",
11      "link": "'https://trading.lemon.markets/v1/account/documents/doc_pyNjNcc77ht3T3lH8dJa5fD8jhj2JHJ1xX",
12      "viewed_first_at": "2021-10-19T14:58:52.813Z",
13      "viewed_last_at": "2021-10-19T14:58:52.813Z"
14    },
15    {
16      ....
17    }
18  ],
19  "previous": "https://paper-trading.lemon.markets/v1/account/documents?limit=20&page=1",
20  "next": "https://paper-trading.lemon.markets/v1/account/documents?limit=2&page=3",
21  "total": 80,
22  "page": 2,
23  "pages": 4
24}
25  

GET /account/documents/{document_id}

Additionally, you can call a document directly via its ID and thereby initiate a PDF download directly.

https://paper-trading.lemon.markets/v1/account/documents/{document_id}

or

https://trading.lemon.markets/v1/account/documents/{document_id}

Request

To download a specific document, specify your request as follows:

Path Parameters

document_id
string
required

The unique Identification number of the document you wish to download

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)

GET/account/documents/{document_id}
1import requests
2import json
3
4paper_trading_key = 'YOUR-PAPER-TRADING-KEY'
5request = requests.get("https://paper-trading.lemon.markets/v1/account/documents/{document_id}",
6          headers={"Authorization": f"Bearer {paper_trading_key}"})
7print(request.json())