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. 😉
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:
or
Request
To retrieve your account information, 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)
Response
Response Parameters
Unique Identification number for your account
Your first name
Your last name
IBAN of the brokerage account at our partner bank. This is the IBAN you can transfer money from your referrence account to.
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.
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).
This number shows you how much cash you have left to invest. The cash_to_invest calculates as follows:
(balance) - (amount_open_orders)
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).
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).
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).
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).
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).
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
Timestamp of your API request
API returns "ok" when account was successfully retrieved.
Environment the request was placed in: "paper" or "money"
Timestamp for when you created your account
Your specified email address
Your specified phone number
Your specified address
The billing address you provided for your account
The billing email address you provided for your account
The billing name you provided for your account
The billing VAT number you provided for your account
The mode your account is currently on - "paper" or "money"
Identification Number of your securities account
The internal client identification number related to your account
The account reference number
Bank name your reference account is located at
Timestamp of live trading account approval
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.
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.
Your tax tax allowance - between 0 and 801 €, as specified in your onboarding process
Relevant start date for your tax allowance (usually 01/01/ of respective year)
Relevant end date for your tax allowance (usually 31/12/ of respective year)
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())
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:
or
Withdrawing Paper Money
Request
To make a withdrawal to your reference account, 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)
Request Body Parameters
Request Body
You can send your request using the following content-types:
- application/json
- application/x-www-form-urlencoded
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.
This is the personal verification PIN you set during the onboarding.
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
Timestamp of your request
API returns "ok" when money was successfully withdrawn.
Environment the request was placed in: "paper" or "money"
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())
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:
or
Request
To retrieve your withdrawals, 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
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
A unique Identification Number of your withdrawal
The amount that you specified for your withdrawal
Timestamp at which you created the withdrawal
Timestamp at which the withdrawal was processed by our partner bank
Your own unique idempotency key that you specified in your POST request to prevent duplicate withdrawals.
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 response
Shows status "ok" when withdrawals were successfully retrieved
Environment the request was placed in: "paper" or "money"
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())
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.
or
Request
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 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
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.
Filter for bank statements until a specific date. Format: "YYYY-MM-DD".
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).
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
Unique Identification Number of your bank statement
Unique Identification Number of the account the bank statement is related to
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
The date that the bank statement relates to (YYYY-MM-DD)
The amount associated with the bank statement
The International Securities Identification Number (ISIN) related to your bank statement. Only for type order_buy and order_sell, otherwise null
The title of the International Securities Identification Number (ISIN) related to your bank statement. Only for type order_buy and order_sell, otherwise null
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
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 response
Shows status "ok" when withdrawals were successfully retrieved
Environment the request was placed in: "paper" or "money"
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())
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:
or
Request
To retrieve a list of your documents, 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)
Response
Response Parameters
Timestamp of request
Environment the request was placed in: "paper" or "money"
API returns "ok" when documents were successfully retrieved
The unique Identification Number for the document
The name of the Document
Timestamp at which the Document was created internally
The Document Category
A Link to download a Document PDF
Timestamp at which the Document was first viewed (downloaded)
Timestamp at which the Document was last viewed (downloaded)
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())
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.
or
Request
To download a specific document, specify your request as follows:
Path Parameters
The unique Identification number of the document you wish to download
Header Parameters
Set your Authorization header in the format "Authorization: Bearer YOUR-API-KEY"
(see the example in the code snippet on the right)
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())