Auto Sweep

Centralized platforms, such as exchanges, neobanks, asset managers, lending desks, payment service platforms, custody platforms, etc., all face the challenge of how to efficiently and cost-effectively collect digital assets deposited by users.

This tutorial will help you:

1. Understand sweeping and fueling.
2. Learn how to complete digital asset sweeping through Auto-Sweep and Safeheron API.

Sweeping

Generally speaking, platforms like exchanges or lending desks will provide an independent deposit wallet for each user. When multiple users deposit digital assets into their deposit wallets, these assets will become distributed across various wallets, which can be inconvenient for unified management and use. Consequently, many platforms collect these assets into a wallet account, a process referred to as sweeping.

Fueling

When it is necessary to sweep ERC-20, TRC-20, and other smart contract-based tokens or transfer them to other wallets, a certain amount of native cryptocurrency must be paid as gas to complete the sweeping or transfer. For example, when a user deposits ERC-20 tokens into a newly created wallet, we cannot sweep them because there are no ETH in the user's wallet to pay for gas. To complete the sweeping, a certain amount of ETH needs to be transferred to this user's wallet to pay for the gas required, which is called fueling.

Sweep Assets

In Safeheron, digital asset sweeping can be automated in two ways:

• Auto Sweep (Recommended)
• Self-Service Sweeping using API

Comparison on 2 methods:

	Auto Sweep (recommended)	Self-Service Sweeping using API
API Co-Signer	Required	Optional
Development Expenses	At almost no cost	At relatively high costs; You need to develop applications similar to Auto Sweep
Wallets Supported	Only asset wallets created through API and labeled as DEPOSIT	All asset wallets
Completion of Sweeping	Auto-completed by auto-sweep policies	Completed through the interface Create a Transaction
Query Records of Sweeping and Fueling Transactions via API	Supported	Supported
Webhook Notifications	Supported	Supported
Web Console	The platform transaction type in the History is displayed as Sweep or Fuel Gas	No additional label in History and its platform transaction type is displayed as General

Auto Sweep

Auto Sweep is a bot application primarily tailored for institutional clientele, offering automated asset sweeping. Please click here for detailed auto-sweep introduction.

tip

The following are required for Auto Sweep:

1. Install the latest Safeheron App (1.2.7 and above).
2. Deploy the API Co-Signer.

Deploy the API Co-Signer

If you have deployed the API Co-Signer, there is no need to deploy it again; if you have not, please click here to learn more about API Co-Signer and contact Safeheron Support for deployment and user guides.

Label Wallets

Auto Sweep only sweep digital assets in wallets that are created through the API and labeled with DEPOSIT. You can label wallets in two ways:

1. When utilizing interface Create a Wallet Account or Batch Create Wallet Accounts V2 to create wallets, set the parameter accountTag to DEPOSIT.
2. After creating the wallet, utilize interface Batch Label Wallet Accounts to relabel the wallet as DEPOSIT.

Example Parameters:

Create a Wallet Account

{
    // Note: Only key parameters are shown. When calling the interface, 
    // please encrypt and sign the parameters. 
    // Please refer to the API authentication section in the API documentation for details.
    "accountName": "example",
    "hiddenOnUI": true,
    "accountTag": "DEPOSIT"
}

Batch Create Wallet Accounts

{
    // Note: Only key parameters are shown. When calling the interface, 
    // please encrypt and sign the parameters. 
    // Please refer to the API authentication section in the API documentation for details.
    "accountName": "example-prefix",
    "count": 10,
    "accountTag": "DEPOSIT"
}

Batch Label Wallet Accounts

{
    // Note: Only key parameters are shown. When calling the interface, 
    // please encrypt and sign the parameters. 
    // Please refer to the API authentication section in the API documentation for details.
    "accountKeyList": ["account08***694ca","accountfd***5e0b7","account4b***1bc55"],
    "accountTag": "DEPOSIT"
}

Configure Auto-Sweep Policy

You can tailor auto-sweep policies on multiple dimensions, such as blockchain network, triggering condition, sweeping frequency, network fee cap, Gas Station, etc. Click here for detailed instructions on configuring auto-sweep policies.

Execute Auto-Sweep Policy

When a wallet with a DEPOSIT label receives digital assets (only tokens supported by Safeheron) and meets the triggering condition of the auto-sweep policy, Auto Sweep will automatically initiate the sweeping task. If you have enabled Gas Station, when the gas of the wallet being swept is insufficient, Auto Sweep will automatically fund this wallet, that is, to fuel gas for the wallet from the Gas Station. The entire process is completed automatically. Please note that executing sweeping once for a wallet may have one sweeping transaction record and one fueling transaction record, or it may only have one sweeping transaction record. This is determined by whether there will be auto-fueling by Gas Station.

API Co-Signer Auto-Approves and Signs Transactions

Like other transaction tasks, once Auto Sweep initiates a sweeping or fueling, API Co-Signer will request the authorization from your approval system to proceed with approval. And, whether allowing the API Co-Signer to sign the transaction or not is determined by your transaction approval system. To distinguish from other transaction tasks, all sweeping and fueling transactions initiated by Auto Sweep have the transaction data as follows:

• The value of transactionType is AUTO_SWEEP for sweeping transactions
• The value of transactionType is AUTO_FUEL for fueling transactions

{
  // Note: Only part of the data is shown
  "sourceAccountKey": "account4b***34234",
  "sourceAccountType": "VAULT_ACCOUNT",
  "sourceAddress": "0xCa***4FBC5",
  "destinationAccountKey": "account46***a2158",
  "destinationAddress": "0xC1***34234",
  "transactionType": "AUTO_SWEEP",
  "transactionStatus": "SUBMITTED",
  "txFee": "0.000106841386050000",
  "feeCoinKey": "ETH(SEPOLIA)_ETHEREUM_SEPOLIA",
  "customerRefId": "a1ef6672-***-ff30d392e723",
  "customerExt1": "1",
  "customerExt2": "2",
  "txAmountToUsd": "19.9813552",
}

tip

Please note that since sweeping and fueling transactions are initiated by Auto Sweep, you may not have the corresponding transaction records in your business system during API Co-Signer approval; even if you have synchronized transaction records through the transaction query interface or webhook, it is not guaranteed that the transaction records are synchronized before the approval completed.

Transaction History and Webhook Notifications

Like other transaction tasks, you can query sweeping and fueling transactions by Auto Sweep in the following four ways:

• View sweeping and fueling transaction records in the History -> Asset Wallet Transaction on the Web Console.
• Obtain sweeping and fueling transaction records through interface Transaction List V2.
• View the sweeping and fueling history of a certain wallet in its "Transaction History" in Safeheron App.
• Also, if you have configured a webhook, records of sweeping and fueling transactions will also be notified through webhook to the callback address you configured.

To distinguish from other transaction tasks, all sweeping and fueling transactions initiated by Auto Sweep have the transaction data as follows:

• The value of transactionType is AUTO_SWEEP for sweeping transactions
• The value of transactionType is AUTO_FUEL for fueling transactions

{
  // Note: Only part of the data is shown
  "sourceAccountKey": "account4b***34234",
  "sourceAccountType": "VAULT_ACCOUNT",
  "sourceAddress": "0xCa***4FBC5",
  "destinationAccountKey": "account46***a2158",
  "destinationAddress": "0xC1***34234",
  "transactionType": "AUTO_SWEEP",
  "transactionStatus": "SUBMITTED",
  "txFee": "0.000106841386050000",
  "feeCoinKey": "ETH(SEPOLIA)_ETHEREUM_SEPOLIA",
  "customerRefId": "a1ef6672-***-ff30d392e723",
  "customerExt1": "1",
  "customerExt2": "2",
  "txAmountToUsd": "19.9813552",
}

Self-Service Sweeping Using API

tip

If you have deployed an API Co-Signer, it is recommended to use Auto Sweep to complete the digital asset sweeping.

The following are required for sweeping via API:

1. Initiate transactions using interface Create a Transaction /v2/transactions/create.
2. Approve and sign the transaction through the Safeheron App or API Co-Signer.

Take a scenario for example:

You have an exchange (referred to as the platform). When a new user Pillar has registered, the platform needs to create a new wallet (or you can pre-create a batch of wallets and choose an unused one) and provide it for Pillar as a deposit wallet. Pillar transfers some USDT (ERC-20) into the wallet, and the platform needs to sweep these assets into the platform's hot withdrawal wallet. To complete the sweeping, the platform transfers some ETH from the hot withdrawal wallet (you can also set up a dedicated wallet for fueling) to Pillar's deposit wallet as gas. Example data as follows:

Item	Example Value
accountKey of Pillar's Deposit Wallet	account2f0e3de53e474037a8fd8e9e672c34d0
accountKey of the Platform's Hot Withdrawal Wallet	account6f85b6e5b800417ebe99209454efcb06
coinKey of Gas Fee Symbol	ETH
coinkey of Deposited Asset Symbol	USDT_ERC20
Deposit Amount	10000 USDT

Create Transactions

Both sweeping and fueling transactions are essentially general transactions that transfer assets and can be implemented through the interface Create a Transaction. Whether fueling is needed is determined by whether the gas in the deposit wallet is sufficient, and not every sweeping requires fueling, that is:

• When the deposit wallet has no gas or insufficient gas, you need to fuel first then sweep, requiring to initiate two transactions.
• When the deposit wallet has sufficient gas, you can directly sweep, requiring only one transaction.

Example parameters when creating a fueling transaction and a sweeping transaction:

Creating a Fueling Request

{
    // Note: Only key parameters are shown. When calling the interface, 
    // please encrypt and sign the parameters. 
    // Please refer to the API authentication section in the API documentation for details.
    // accountKey of the platform's hot withdrawal wallet
    "sourceAccountKey":"account6f85b6e5b800417ebe99209454efcb06",
    "sourceAccountType":"VAULT_ACCOUNT",
    // Pillar's deposit wallet
    "destinationAccountKey":"account2f0e3de53e474037a8fd8e9e672c34d0",
    "destinationAccountType":"VAULT_ACCOUNT",

    // coinKey of gas fee symbol
    "coinKey":"ETH",
    // It is recommended that each fueling amount can be used to 
    // pay for the fees of 3 to 5 transactions.
    "txAmount":"some amount eth",
    // This example uses a transaction fee rate grade, 
    // but you can also use the parameters of the fee model of the corresponding chain.
    "txFeeLevel":"MIDDLE",
    // The caller is responsible for generating and ensuring uniqueness.
    "customerRefId":"a1ef66******92e723",
}

Creating a Sweeping Request

{
    // Note: Only key parameters are shown. When calling the interface, 
    // please encrypt and sign the parameters. 
    // Please refer to the API authentication section in the API documentation for details.
    // Pillar's deposit wallet
    "sourceAccountKey":"account2f0e3de53e474037a8fd8e9e672c34d0",
    "sourceAccountType":"VAULT_ACCOUNT",
    // accountKey of the platform's hot withdrawal wallet
    "destinationAccountKey":"account6f85b6e5b800417ebe99209454efcb06",
    "destinationAccountType":"VAULT_ACCOUNT",

    // Symbol of deposited asset
    "coinKey":"USDT_ERC20",
    // Sweeping amount
    "txAmount":"10000",
    // This example uses a transaction fee rate grade, 
    // but you can also use the parameters of the fee model of the corresponding chain.
    "txFeeLevel":"MIDDLE",
    // The caller is responsible for generating and ensuring uniqueness.
    "customerRefId":"a1ef66******92e723",
}

Approve and Sign Transactions

Once a transaction task has been created, the system will proceed with either manual or automated approval via the API Co-Signer based on your policies.

Manual Approval

After the transaction is created, the Safeheron App will receive a push notification, and the pending task will be displayed in "Pending". Once approved, the App of the final approver will participate in completing the signature.

API Co-Signer Approval

The API Co-Signer will automatically retrieve the approval-pending transaction and request authorization from your business system to approve the transaction. After being authorized, the API Co-Signer will complete the signing.