Upvest provides time-weighted returns (TWR) for individual accounts via its API.
Time-weighted return is a proven method of measuring account performance. It ignores external cash flows and only reflects the performance of the account based on the structure of the positions.
For this purpose, Upvest offers daily calculations of time-weighted returns in webhook events and an endpoint for accessing the time series of historical returns.
Time-weighted return is one of the many ways to measure an investment portfolio’s performance. Specifically, it abstracts away external flows (such as buy or sell orders, account transfers, etc.) and mainly focuses on how the portfolio composition/price behaviour of the securities affects the portfolio performance. Time-weighted return is a relative measure and is calculated in percentages (e.g., +1,8%, -0,34%).
Upvest’s calculation of the return is based on the valuation of the account and record of all external flows in and out of the account. Returns are calculated at the end of each day.
Intra-day calculations are not currently available.
- Account valuation: Serves as a base for the calculation. Account valuation is based on the end-of-day security positions and end-of-day prices of these securities.
- External flows: Are excluded from the valuation. Examples of external flows are:
- Buy/sell orders (including orders to cover outstanding fees or tax payments)
- Outgoing/incoming account transfers
- Tax refunds
Upvest doesn’t take into account cash balances of the user, only amounts invested in the securities account.
The following example shows the impact of different actions on the time-weighted return calculation over the course of 5 days from the opening of the account.
| Day | Action | EOD valuation | Daily return | Cumulative return |
|---|---|---|---|---|
| 0 | An account is created with 100 Euros. | 100 euro | - | - |
| +1 | Invested instruments increase in value by 5 euros. | 105 euro | +5% | +5% |
| +2 | The user sells 50 euros of securities with no price change. | 55 euro | 0% | +5% |
| +3 | The user buys 100 euros of securities with no price change. | 155 euro | 0% | +5% |
| +4 | No price change but the user receives and withdraws a 5 euro dividend. | 155 euro | +3.23% | +8.39% |
To retrieve the history of daily returns data of a specified account, submit the following call to the API:
GET /accounts/{account_id}/returns
Path parameter
| Parameter | Description | Example |
|---|---|---|
account_id | Required: The unique identifier of the user's account. | 51cdc0cc-9042 11ed-b0172eabd 0c03f8a |
Optional query parameters
| Parameter | Description | Example |
|---|---|---|
start_date | Optional: The start date for the time series of returns (including the specified date). | 2024-01-01 |
end_date | Optional: The end date for the income time series. | 2024-01-31 |
If both the start and end dates are empty, the Investment API returns data of the last month.
Example response
{
"meta":{
"offset": 0,
"limit": 100,
"count": 2,
"total_count": 2,
"sort": "date",
"order": "ASC"
},
"data": [
{
"account_id": "bbe9e784-e009-4cb6-a07c-24831897327b",
"date": "2023-09-01T00:00:00Z",
"twr": {
"daily": "0.0132434142",
"cumulative": "0.0324353234",
"cumulative_start_date": "2023-08-01T00:00:00Z"
}
},
{
"account_id": "bbe9e784-e009-4cb6-a07c-24831897327b",
"date": "2023-09-02T00:00:00Z",
"twr": {
"daily": "-0.005116543491",
"cumulative": "0.0271528232",
"cumulative_start_date": "2023-08-01T00:00:00Z"
}
}
]
}