Wallet Topup module
An automation module to monitor and ensure minimum wallet balances
Supercool's Wallet Topup module can monitor ERC-20 and native token (ETH, MATIC, etc.) balances to ensure they always have enough of their expected funds. For example, you can monitor the ETH balance of a set of wallets and whenever a wallet gets below 0.5 ETH, Supercool will automatically swap USDC from a treasury account into ETH and transfer to the low-balance wallet.
If necessary, Supercool will swap between token types and bridge between chains according to your rules. Swaps are done via Uniswap, which takes a 0.3% fee of the balance swapped.
You first need to fund a relayer with ETH (or other native currency) to pay for gas when executing your auto-funding rules.
Then you set up wallet funding rules, which monitor certain wallet balances and decide when and how to top up that wallet's balance. Each rule specifies where the tokens will be transferred from (the "treasury"), where they will be transferred to, and when the transfer should occur.
For ERC-20 tokens, the parts of a wallet funding rule are:
- source chain: the chain ID ("ethereum", "polygon", etc.) of the treasury
- source address: account address to transfer ERC-20 tokens from
- target chain: combined with target address to specify the wallet being monitored and funded
- target address: combined with target chain
- source token address: on the source chain, the address of the ERC-20 token contract to transfer from
- target token address: on the destination chain, the ERC-20 token contract address for the tokens we will be sending to the target wallet address
- minimum balance: the minimum allowed
uint256balance of the target token; when the target address's balance becomes less than (that's<, not<=), a transfer is initiated - top-up limit: the
uint256balance of the target wallet and token that Supercool will top the target address up to
For native tokens, the rules are slightly different. You must transfer native tokens from a relayer account, since you cannot approve another address to transfer native tokens. The rule parameters when the input token is a native token:
- relayer ID: the underlying relayer account that will perform the transfer
- target chain
- target address
- target token address
- minimum balance
- top-up limit
If setting rules programatically via our API, the minimum balance and top-up limit must be specified as a string to avoid integer rounding errors due to integer width. For example, Javascript integers are 4 bytes wide, while Solidity
uint256 is 32 bytes wide.For ERC-20 tokens, there are two ways to configure your funding source. The source can either be one of the underlying relayer accounts or it can be a different treasury address. If the treasury address is different than the relayer address, you must grant ERC-20 transfer approval to Supercool's swap contract. See swapper contract addresses below.
Note that each underlying relayer account belongs exactly to one user. In other words, if you have a relayer account
0xfeedbad, then you are the only one with access to that account.Here's an example rule on Optimism:
- source chain:
optimism - source address:
0xdeadbeef(your treasury address here) - target chain:
optimism - target address:
0xbadfad(your target wallet address here) - source token address:
0x7f5c764cbc14f9669b88837ca1490cca17c31607(USDC) - target token address:
0x0000000000000000000000000000000000000000(use the 0 address for native currency) - minimum balance:
"30000000000000000"(0.03 ETH) - top-up limit:
"100000000000000000"(0.1 ETH)
When the
0xbadfad wallet on Optimism goes below 0.03 ETH, Supercool will automatically swap enough USDC to ETH to fund the wallet back up to 0.1 ETH.These are the underlying swapper addresses that can swap your ERC-20 tokens. For any source token, you need to grant ERC-20 transfer approval to these addresses up to whatever token balance you feel comfortable approving.
Chain | Address |
|---|---|
goerli | 0x1EeE3FF4ec066B575D6D3b1A306386D0C2A71340 |
polygon | 0x8a371d4D430812d0948eC7830c632Eb7E8C11ADe |
optimism | 0x8a371d4D430812d0948eC7830c632Eb7E8C11ADe |
Right now, the wallet topup module treasury must be an on-chain account, but we can do custom integrations to support other treasury sources. If you want to fund your wallets from a centralized source, such as Coinbase, or via credit card, please reach out to us at [email protected].
Last modified 3d ago