Predict Top-Ups

Forecasting is a Smart Treasury feature that uses historical transaction data to predict upcoming fund needs for your wallets. It helps ensure your funds are in the right place at the right time, thus reducing the risk of unnecessary borrowing or failed transactions.

Overview

Forecasting uses machine learning to analyse daily and weekly transaction trends in each wallet. It anticipates future cash flow needs based on your past activity. Note that forecasting accuracy and reliability heavily depend on the quality and quantity of historical data available. For machine learning models to produce meaningful and accurate predictions, they require a substantial amount of relevant historical information.

After enabling the Forecasting feature, the system compares forecasted payments for the next X hours. This time window is defined in the minBalanceWindowWidth / targetBalanceWindowWidth parameters.

Based on this static and dynamic data, the feature can make predictions and dynamically change the thresholds.

When a wallet is projected to dip below safe levels, the system:

Identifies which source wallets (e.g. master wallets or exchanges) have available funds.
Selects the most efficient source based on balance and simplicity of transfer.
Triggers the withdrawal and sends a notification about it.
Uses the Level1 workflow to request approval via API or Portal:
- If static thresholds are used, no approval is needed.
- If forecasting-based logic triggers the adjustment, approval is requested via the Portal or API.

Once approved, funds are transferred; conversion is automatically performed if the source currency is different.

The operation is automatically and safely cancelled if the system receives no approval within a specific timeframe.

Get forecasts

Update the current thresholds and enable Forecasting, send the PUT /treasury/v1/managed-balances/{managedBalanceId} request with the following body parameters:
```
"thresholds": {
    "minBalance": 500000,
    "warningBalance": 800000,
    "targetBalance": 1000000,
    "minBalanceWindowWidth": 2,
    "warningBalanceWindowWidth": 3,
    "targetBalanceWindowWidth": 6,
    "minBalanceBufferFactor": 0.2,
    "transferOperationHardTimeout": "PT1H"
  },
    
    "forecastDisabled": true
```
Here,
- In thresholds, specify the following:
  - minBalance / targetBalance: Desired minimum and target balance.
  - minBalanceBufferFactor: Offset to always keep a specific amount of funds.
  - minBalanceWindowWidth / targetBalanceWindowWidth: Time window in hours to be analysed for forecasts.
  - warningBalanceWindowWidth: Time window that specifies how far into the future the system checks your forecasted balance before deciding to raise an alert. For example, if set to 2 hours, the system projects your balance two hours ahead. If that forecast falls below your warningBalance threshold, an alarm will be issued.
- Set forecastDisabled to true to enable forecasting.
- Specify eligible funding wallets/exchanges; the model will rank them automatically. The model will:
  - Prefer same-currency sources.
  - Evaluate conversion cost when a currency swap is unavoidable.
  - Avoid sources whose own forecast shows they’ll dip too low.
- Metadata: set up once.
Configure webhooks for forecast alerts & approval prompts.
Use the hook service to get alerts:
- When forecasting detects a low balance
- When a transfer is triggered or fails
- When threshold updates or approvals are needed
Approve requests through API or Portal. Unapproved requests time out and are safely cancelled:
- In Portal: click Approve / Reject.
- Via API: send the POST digital/v1/screenings/action request with transfer ID and the destination address ID.
Monitor update thresholds anytime; the model continually improves with every transaction.

Example use case

Emily, a treasury manager at the Dunwall fintech company, had set a minimum balance threshold of 50,000 USD for their Ethereum wallet used for customer payouts.

One Monday, the wallet held 53,000 USD. The Forecasting system predicted 10,000 USD would be spent in the next 12 hours. Despite the relatively low forecasted spend, the system aimed to maintain the 50,000 USD safety buffer.

It evaluated the available source wallets:

Kraken: 6,000 USD
Binance: 120,000 USD, but takes more steps to execute
Tron wallet: 84,000 USD and fast

Forecasting chose the Tron wallet due to its high balance and minimal transfer steps. It triggered a 12,000 USD top-up request, notified Emily in Slack, and sent the request for approval via the Portal. Emily approved the request, and the system executed the transfer. The conversion from Tron to Ethereum was handled automatically.

Shortly after, the Ethereum wallet was topped up, and Emily received a notification:

“Top-up from Tron wallet completed. 12,000 USD was added to the Ethereum wallet to maintain the threshold.”