Introduction

The Investment API provides a virtual cash system for tracking and managing virtual funds for your end users.

Upvest provides endpoints for increasing and decreasing the cash balance of the selected account group for this purpose.

Please note that the virtual cash management feature is only available in the single account, post-trade settlement setup.

In this guide you will learn how virtual cash works and how to implement it.

How does virtual cash management work?

The virtual cash management feature enables an increase to be triggered before an order is placed and a decrease to be triggered after the order execution has been completed.

This functionality not only simplifies the complexity of tracking cash that has not yet settled, but extends additional use cases, e.g. portfolio management and rebalancing, automatic reinvestment of cash dividends, sales to cover fees and reinvestment of tax refunds.

In some use cases, virtual cash management streamlines processes: by increasing the cash balance, you can enable trading, whereas decreasing it reduces the tradable balance (e.g. when your customer withdraws cash). In this context, the backlog plays an important role.

Backlog

A backlog is essentially a way to delay the processing of an order, withdrawal or other cash-reducing transaction without the credit being immediately in the account. This feature allows you to interact asynchronously with the Upvest API, for example:

Orders are not immediately cancelled if the deposit is made a little later than the order was placed.
Withdrawals wait for the money to arrive before they are executed.
Each time an item is placed in the queue for the virtual cash backlog, you will be notified of the VIRTUAL_CASH_DECREASE.QUEUED event.

Note that in all these operations there is no automatic rejection for lack of money. These cases end up in the backlog:

Not enough funds for an order which currently does not have a QUEUED state.
Not enough funds for a decrease.

This means that although a sell order is placed first, the cash balance is not automatically reduced immediately, but only when the sell order is settled.

To learn more about the different use cases, go to this chapter.