Auto top-up wallet

In this guide, we’ll walk you through building a Web3 wallet auto top-up system using Kwala Workflows, a low-code, YAML-based automation platform for blockchain developers. With Kwala, you can connect on-chain events to automated smart contract executions without cron jobs, servers, or custom scripts. In this use case, you’ll learn how to automatically monitor wallet balances and top-up low balances in real time through smart contracts and event-driven workflows powered by Kwala.

Objective

Build a two-part workflow system that:

Continuously checks wallet balances and detects when a wallet’s native POL balance drops below a threshold of 0.1 POL.
Automatically transfers funds to top up the wallet whenever a low-balance event is emitted.

This setup enables self-sustaining wallets that stay funded without manual monitoring.

Step 1: Smart contract setup

We use two Solidity contracts:

1. `PolNativeBalanceChecker.sol`

This contract checks a wallet’s POL balance and emits a LowPolBalance event when the balance is below the predefined threshold. File name: PolChecker.sol

// SPDX-License-Identifier: MIT
pragma solidity ^0.8.20;

/// @title PolNativeBalanceChecker
/// @notice Emits LowPolBalance(user,balanceWei) when a checked address balance < THRESHOLD (0.1 POL).
contract PolNativeBalanceChecker {
    uint256 public constant THRESHOLD = 0.1 ether; // 0.1 POL

    event LowPolBalance(address indexed user, uint256 balanceWei);

    /// @notice Returns native balance in wei
    function polBalanceOf(address user) public view returns (uint256) {
        return user.balance;
    }

    /// @notice Check `user` balance and emit event if below threshold.
    function checkAndWarn(address user) public returns (uint256 balanceWei) {
        balanceWei = user.balance;
        if (balanceWei < THRESHOLD) {
            emit LowPolBalance(user, balanceWei);
        }
    }

    /// @notice Convenience: check caller
    function checkMe() external returns (uint256) {
        return checkAndWarn(msg.sender);
    }
}

Deploy this contract on Polygon Amoy Testnet and copy the deployed contract address, for example: 0x85bc99d6207aD8284fb2bD0C5A4ebaA6F4B140e4.

2. `AutoTopUp.sol`

This contract performs the top-up of wallets that fall below the balance threshold. File name: AutoTopUp.sol

// SPDX-License-Identifier: MIT
pragma solidity ^0.8.20;

/// @title AutoTopUp
/// @notice Minimal "self-executable" top-up vault.
/// - If `to` has < 0.1 POL, calling `topUpIfLow(to)` will send 1 POL from this contract to `to`.
/// - Anyone can call `topUpIfLow` (so it is "self-executable"); the contract must be funded first.
/// - Includes a tiny non-reentrant guard.
contract AutoTopUp {
    uint256 public constant TOPUP_AMOUNT = 1 ether;      // send 1 POL
    uint256 public constant THRESHOLD   = 0.1 ether;     // top-up when recipient < 0.1 POL

    bool private locked;

    event TopUpExecuted(address indexed to, uint256 amountWei);
    event TopUpSkipped(address indexed to, uint256 currentBalanceWei);
    event Received(address indexed from, uint256 amountWei);

    modifier nonReentrant() {
        require(!locked, "reentrant");
        locked = true;
        _;
        locked = false;
    }

    // allow the contract to receive POL (treasury should send funds here)
    receive() external payable {
        emit Received(msg.sender, msg.value);
    }

    /// @notice If `to` has balance < THRESHOLD, transfer TOPUP_AMOUNT from this contract to `to`.
    /// @dev Callable by anyone. Returns true on successful transfer, false if skipped due to sufficient balance.
    function topUpIfLow(address payable to) external nonReentrant returns (bool) {
        require(to != address(0), "invalid recipient");

        uint256 recipientBal = to.balance;
        if (recipientBal >= THRESHOLD) {
            emit TopUpSkipped(to, recipientBal);
            return false;
        }

        require(address(this).balance >= TOPUP_AMOUNT, "insufficient vault balance");

        (bool sent, ) = to.call{ value: TOPUP_AMOUNT }("");
        require(sent, "transfer failed");

        emit TopUpExecuted(to, TOPUP_AMOUNT);
        return true;
    }

    /// @notice View helper: whether a top-up would succeed right now.
    function canTopUp(address to) public view returns (bool) {
        if (to == address(0)) return false;
        return (to.balance < THRESHOLD) && (address(this).balance >= TOPUP_AMOUNT);
    }

    /// @notice Convenience: current contract (vault) balance
    function vaultBalance() external view returns (uint256) {
        return address(this).balance;
    }
}

Deploy AutoTopUp and fund it with enough POL so it can perform top-ups.

Step 2: Setting up Kwala workflows

This automation uses two Kwala workflows that communicate via emitted events.

Workflow 1: BCPollingperMinute polling workflow

Purpose: Continuously monitor a wallet’s POL balance by calling checkAndWarn(). Trigger parameters:

Execute After: immediate
Repeat Every: 1m every minute
Expires In: 1759213800 timestamp

Action: Calls checkAndWarn(address user) on the deployed PolNativeBalanceChecker contract. If the wallet’s balance is below 0.1 POL, the contract emits LowPolBalance(address,uint256). YAML 1: Polling workflow

Name: polling1_e81e
Trigger:
  TriggerSourceContract: NA
  TriggerChainID: NA
  TriggerEventName: NA
  TriggerEventFilter: NA
  TriggerSourceContractABI: NA
  TriggerPrice: NA
  RecurringSourceContract: NA
  RecurringChainID: NA
  RecurringEventName: NA
  RecurringEventFilter: NA
  RecurringSourceContractABI: NA
  RecurringPrice: NA
  RepeatEvery: 1m
  ExecuteAfter: immediate
  ExpiresIn: 1759213800
  Meta: NA
  ActionStatusNotificationPOSTURL: 
  ActionStatusNotificationAPIKey: NA
Actions:
  - Name: poll1
    Type: call
    APIEndpoint: NA
    APIPayload:
      Message: NA
    TargetContract: 0x85bc99d6207aD8284fb2bD0C5A4ebaA6F4B140e4
    TargetFunction: function checkAndWarn(address user)
    TargetParams:
      - 0x0F0C0b9683180DF0a13Fc176aFFd92E1F7f380f0
    ChainID: 80002
    EncodedABI: NA
    Bytecode: NA
    Metadata: NA
    RetriesUntilSuccess: 5
Execution:
  Mode: sequential

The polling workflow calls the checker every minute for the target wallet address, for example: 0x0F0C…f380f0.

Workflow 2: AutoTopUp1 auto top-up workflow

Purpose: Automatically top up wallets whenever a LowPolBalance event is emitted. Trigger parameters:

Trigger Source Contract: 0x85bc99d6207aD8284fb2bD0C5A4ebaA6F4B140e4
Trigger Chain ID: 80002 Polygon Amoy
Trigger Event Name: LowPolBalance(address,uint256)
Execute After: event
Repeat Every: event

When triggered, this workflow calls the AutoTopUp contract’s topUpIfLow() function to send funds. YAML 2: AutoTopUp workflow

Name: autotopup1_e81e
Trigger:
  TriggerSourceContract: 0x85bc99d6207aD8284fb2bD0C5A4ebaA6F4B140e4
  TriggerChainID: 80002
  TriggerEventName: LowPolBalance(address,uint256)
  TriggerEventFilter: NA
  TriggerSourceContractABI: WwogIHsKICAgICJhbm9ueW1vdXMiOiBmYWxzZSwKICAgICJpbnB1dHMiOiBbCiAgICAgIHsKICAgICAgICAiaW5kZXhlZCI6IHRydWUsCiAgICAgICAgImludGVybmFsVHlwZSI6ICJhZGRyZXNzIiwKICAgICAgICAibmFtZSI6ICJ1c2VyIiwKICAgICAgICAidHlwZSI6ICJhZGRyZXNzIgogICAgICB9LAogICAgICB7CiAgICAgICAgImluZGV4ZWQiOiBmYWxzZSwKICAgICAgICAiaW50ZXJuYWxUeXBlIjogInVpbnQyNTYiLAogICAgICAgICJuYW1lIjogImJhbGFuY2VXZWkiLAogICAgICAgICJ0eXBlIjogInVpbnQyNTYiCiAgICAgIH0KICAgIF0sCiAgICAibmFtZSI6ICJMb3dQb2xCYWxhbmNlIiwKICAgICJ0eXBlIjogImV2ZW50IgogIH0sCiAgewogICAgImlucHV0cyI6IFtdLAogICAgIm5hbWUiOiAiVEhSRVNIT0xEIiwKICAgICJvdXRwdXRzIjogWwogICAgICB7CiAgICAgICAgImludGVybmFsVHlwZSI6ICJ1aW50MjU2IiwKICAgICAgICAibmFtZSI6ICIiLAogICAgICAgICJ0eXBlIjogInVpbnQyNTYiCiAgICAgIH0KICAgIF0sCiAgICAic3RhdGVNdXRhYmlsaXR5IjogInZpZXciLAogICAgInR5cGUiOiAiZnVuY3Rpb24iCiAgfSwKICB7CiAgICAiaW5wdXRzIjogWwogICAgICB7CiAgICAgICAgImludGVybmFsVHlwZSI6ICJhZGRyZXNzIiwKICAgICAgICAibmFtZSI6ICJ1c2VyIiwKICAgICAgICAidHlwZSI6ICJhZGRyZXNzIgogICAgICB9CiAgICBdLAogICAgIm5hbWUiOiAiY2hlY2tBbmRXYXJuIiwKICAgICJvdXRwdXRzIjogWwogICAgICB7CiAgICAgICAgImludGVybmFsVHlwZSI6ICJ1aW50MjU2IiwKICAgICAgICAibmFtZSI6ICJiYWxhbmNlV2VpIiwKICAgICAgICAidHlwZSI6ICJ1aW50MjU2IgogICAgICB9CiAgICBdLAogICAgInN0YXRlTXV0YWJpbGl0eSI6ICJub25wYXlhYmxlIiwKICAgICJ0eXBlIjogImZ1bmN0aW9uIgogIH0sCiAgewogICAgImlucHV0cyI6IFtdLAogICAgIm5hbWUiOiAiY2hlY2tNZSIsCiAgICAib3V0cHV0cyI6IFsKICAgICAgewogICAgICAgICJpbnRlcm5hbFR5cGUiOiAidWludDI1NiIsCiAgICAgICAgIm5hbWUiOiAiIiwKICAgICAgICAidHlwZSI6ICJ1aW50MjU2IgogICAgICB9CiAgICBdLAogICAgInN0YXRlTXV0YWJpbGl0eSI6ICJub25wYXlhYmxlIiwKICAgICJ0eXBlIjogImZ1bmN0aW9uIgogIH0sCiAgewogICAgImlucHV0cyI6IFsKICAgICAgewogICAgICAgICJpbnRlcm5hbFR5cGUiOiAiYWRkcmVzcyIsCiAgICAgICAgIm5hbWUiOiAidXNlciIsCiAgICAgICAgInR5cGUiOiAiYWRkcmVzcyIKICAgICAgfQogICAgXSwKICAgICJuYW1lIjogInBvbEJhbGFuY2VPZiIsCiAgICAib3V0cHV0cyI6IFsKICAgICAgewogICAgICAgICJpbnRlcm5hbFR5cGUiOiAidWludDI1NiIsCiAgICAgICAgIm5hbWUiOiAiIiwKICAgICAgICAidHlwZSI6ICJ1aW50MjU2IgogICAgICB9CiAgICBdLAogICAgInN0YXRlTXV0YWJpbGl0eSI6ICJ2aWV3IiwKICAgICJ0eXBlIjogImZ1bmN0aW9uIgogIH0KXQ==
  TriggerPrice: NA
  RecurringSourceContract: 0x85bc99d6207aD8284fb2bD0C5A4ebaA6F4B140e4
  RecurringChainID: 80002
  RecurringEventName: LowPolBalance(address,uint256)
  RecurringEventFilter: NA
  RecurringSourceContractABI: WwogIHsKICAgICJhbm9ueW1vdXMiOiBmYWxzZSwKICAgICJpbnB1dHMiOiBbCiAgICAgIHsKICAgICAgICAiaW5kZXhlZCI6IHRydWUsCiAgICAgICAgImludGVybmFsVHlwZSI6ICJhZGRyZXNzIiwKICAgICAgICAibmFtZSI6ICJ1c2VyIiwKICAgICAgICAidHlwZSI6ICJhZGRyZXNzIgogICAgICB9LAogICAgICB7CiAgICAgICAgImluZGV4ZWQiOiBmYWxzZSwKICAgICAgICAiaW50ZXJuYWxUeXBlIjogInVpbnQyNTYiLAogICAgICAgICJuYW1lIjogImJhbGFuY2VXZWkiLAogICAgICAgICJ0eXBlIjogInVpbnQyNTYiCiAgICAgIH0KICAgIF0sCiAgICAibmFtZSI6ICJMb3dQb2xCYWxhbmNlIiwKICAgICJ0eXBlIjogImV2ZW50IgogIH0sCiAgewogICAgImlucHV0cyI6IFtdLAogICAgIm5hbWUiOiAiVEhSRVNIT0xEIiwKICAgICJvdXRwdXRzIjogWwogICAgICB7CiAgICAgICAgImludGVybmFsVHlwZSI6ICJ1aW50MjU2IiwKICAgICAgICAibmFtZSI6ICIiLAogICAgICAgICJ0eXBlIjogInVpbnQyNTYiCiAgICAgIH0KICAgIF0sCiAgICAic3RhdGVNdXRhYmlsaXR5IjogInZpZXciLAogICAgInR5cGUiOiAiZnVuY3Rpb24iCiAgfSwKICB7CiAgICAiaW5wdXRzIjogWwogICAgICB7CiAgICAgICAgImludGVybmFsVHlwZSI6ICJhZGRyZXNzIiwKICAgICAgICAibmFtZSI6ICJ1c2VyIiwKICAgICAgICAidHlwZSI6ICJhZGRyZXNzIgogICAgICB9CiAgICBdLAogICAgIm5hbWUiOiAiY2hlY2tBbmRXYXJuIiwKICAgICJvdXRwdXRzIjogWwogICAgICB7CiAgICAgICAgImludGVybmFsVHlwZSI6ICJ1aW50MjU2IiwKICAgICAgICAibmFtZSI6ICJiYWxhbmNlV2VpIiwKICAgICAgICAidHlwZSI6ICJ1aW50MjU2IgogICAgICB9CiAgICBdLAogICAgInN0YXRlTXV0YWJpbGl0eSI6ICJub25wYXlhYmxlIiwKICAgICJ0eXBlIjogImZ1bmN0aW9uIgogIH0sCiAgewogICAgImlucHV0cyI6IFtdLAogICAgIm5hbWUiOiAiY2hlY2tNZSIsCiAgICAib3V0cHV0cyI6IFsKICAgICAgewogICAgICAgICJpbnRlcm5hbFR5cGUiOiAidWludDI1NiIsCiAgICAgICAgIm5hbWUiOiAiIiwKICAgICAgICAidHlwZSI6ICJ1aW50MjU2IgogICAgICB9CiAgICBdLAogICAgInN0YXRlTXV0YWJpbGl0eSI6ICJub25wYXlhYmxlIiwKICAgICJ0eXBlIjogImZ1bmN0aW9uIgogIH0sCiAgewogICAgImlucHV0cyI6IFsKICAgICAgewogICAgICAgICJpbnRlcm5hbFR5cGUiOiAiYWRkcmVzcyIsCiAgICAgICAgIm5hbWUiOiAidXNlciIsCiAgICAgICAgInR5cGUiOiAiYWRkcmVzcyIKICAgICAgfQogICAgXSwKICAgICJuYW1lIjogInBvbEJhbGFuY2VPZiIsCiAgICAib3V0cHV0cyI6IFsKICAgICAgewogICAgICAgICJpbnRlcm5hbFR5cGUiOiAidWludDI1NiIsCiAgICAgICAgIm5hbWUiOiAiIiwKICAgICAgICAidHlwZSI6ICJ1aW50MjU2IgogICAgICB9CiAgICBdLAogICAgInN0YXRlTXV0YWJpbGl0eSI6ICJ2aWV3IiwKICAgICJ0eXBlIjogImZ1bmN0aW9uIgogIH0KXQ==
  RecurringPrice: NA
  RepeatEvery: event
  ExecuteAfter: event
  ExpiresIn: 1759213800
  Meta: NA
  ActionStatusNotificationPOSTURL: 
  ActionStatusNotificationAPIKey: NA
Actions:
  - Name: autotopup1
    Type: call
    APIEndpoint: NA
    APIPayload:
      Message: NA
    TargetContract: 0x8905777D8617034ACD8088D9273186D449436e6C
    TargetFunction: function topUpIfLow(address payable)
    TargetParams:
      - 0x0F0C0b9683180DF0a13Fc176aFFd92E1F7f380f0
    ChainID: 80002
    EncodedABI: NA
    Bytecode: NA
    Metadata: NA
    RetriesUntilSuccess: 5
Execution:
  Mode: sequential

The auto-top-up workflow listens for LowPolBalance events emitted by the checker contract and then calls the top-up action on the AutoTopUp contract.

Step 3: Deploy and test the workflows

Save and compile both YAML workflows in the Kwala Dashboard.
Deploy Workflow 1 (polling) and Workflow 2 (auto top-up).
Wait until both workflows show Claimed.
Fund the deployed AutoTopUp contract with sufficient POL.

When a monitored wallet’s balance drops below 0.1 POL:

Workflow 1 polling calls checkAndWarn() and the checker emits LowPolBalance.
Workflow 2 detects the event and calls topUpIfLow() on the AutoTopUp contract, which transfers 1 POL to the wallet.

Step 4: Monitor workflow execution

Use the Kwala Dashboard to inspect:

Workflow Logs: verify triggers and action calls.
Execution Status: confirm successful top-ups.
Retries and Failures: troubleshoot any missed or failed attempts.

Output

Once both workflows run successfully, the AutoTopUp contract transfers 1 POL to the wallet address whenever its balance goes below 0.1 POL, creating a self-regulating on-chain wallet. If you add Telegram or other notifications to the workflows, you can surface messages like:

“AutoTopUp executed — wallet 0x0F0C…F380f0 rebalanced successfully.”

Conclusion

With thr two YAML workflows, we created an auto top-up wallet system using Kwala Workflows without backend scripts, centralized orchestration, or manual intervention. This use case highlights how Kwala bridges event-driven Web3 logic with automated smart contract execution, enabling developers to build real-world, autonomous blockchain systems quickly and reliably.

Overview

Getting started

Use the Workflow Builder

Use cases

Concepts

Reference

Resources

Objective

Step 1: Smart contract setup

1. `PolNativeBalanceChecker.sol`

2. `AutoTopUp.sol`

Step 2: Setting up Kwala workflows

Workflow 1: BCPollingperMinute polling workflow

Workflow 2: AutoTopUp1 auto top-up workflow

Step 3: Deploy and test the workflows

Step 4: Monitor workflow execution

Output

Conclusion

Next steps

Monitor Your Workflows

Best Practices

​Objective

​Step 1: Smart contract setup

​1. PolNativeBalanceChecker.sol

​2. AutoTopUp.sol

​Step 2: Setting up Kwala workflows

​Workflow 1: BCPollingperMinute polling workflow

​Workflow 2: AutoTopUp1 auto top-up workflow

​Step 3: Deploy and test the workflows

​Step 4: Monitor workflow execution

​Output

​Conclusion

​Next steps

Monitor Your Workflows

Best Practices

Objective

Step 1: Smart contract setup

1. `PolNativeBalanceChecker.sol`

2. `AutoTopUp.sol`

Step 2: Setting up Kwala workflows

Workflow 1: BCPollingperMinute polling workflow

Workflow 2: AutoTopUp1 auto top-up workflow

Step 3: Deploy and test the workflows

Step 4: Monitor workflow execution

Output

Conclusion

Next steps