Automatic Fund Settlement — Hot-to-Cold Wallet Sweeps

XPayLabs automatically sweeps received funds from hot wallets to your configured cold storage addresses. Learn about the settlement flow, timing, and configuration.

Settlement in XPayLabs refers to the automatic transfer of received funds from your gateway’s hot wallet (where customer payments arrive) to your cold storage wallet (where funds are secured for long-term holding). This process is known as a “sweep” or “collection.”

Unlike traditional payment processors that batch settlements to bank accounts on a T+2 schedule, XPayLabs settlement is a blockchain-native process — funds move directly between your wallets on-chain.

How Settlement Works

Customer Payment        Hot Wallet           Cold Wallet
     |                     |                     |
     |--- USDT arrives --->|                     |
     |                     |-- sweep triggered ->|
     |                     |   (auto or manual)  |
     |                     |                     |
     |                     |<-- sweep confirmed -|
     |<-- Webhook: COLLECT_SUCCESS              |

1. Funds arrive in hot wallet

   When a customer’s payment is confirmed (ORDER_SUCCESS), the USDT (or other token) sits in the gateway’s hot wallet — an online wallet used for receiving payments.

2. Sweep is triggered

   Settlement can be triggered in two ways:

   • Automatic: The gateway monitors accumulated balances and initiates a sweep when configurable thresholds are met (e.g., every 1000 USDT or every hour).
   • Manual: An administrator triggers a sweep through the gateway dashboard.
3. On-chain transfer

   The gateway constructs and signs a blockchain transaction that transfers the accumulated tokens from the hot wallet to the cold storage address. This transaction pays standard blockchain gas fees.

4. Sweep confirmed

   Once the transfer transaction reaches sufficient block confirmations, a COLLECT_SUCCESS webhook is sent. If the transaction fails, COLLECT_FAILED is sent.

Configuration

You configure settlement in the gateway’s application.yml:

xpay:
  settlement:
    cold-wallet-addresses:
      TRON: "TYourColdWalletAddress..."
      ETH: "0xYourColdWalletAddress..."
      BSC: "0xYourColdWalletAddress..."
    auto-sweep:
      enabled: true
      min-amount: "1000"     # Minimum USDT to trigger sweep
      max-amount: "10000"    # Maximum USDT per sweep transaction
      interval: 3600         # Check interval in seconds (1 hour)
    sweep-on-collect: true   # Sweep immediately after each collection

Settlement vs. Payout

	Settlement	Payout
Direction	Hot wallet → Cold wallet	Gateway wallet → External address
Purpose	Secure funds in cold storage	Pay vendors, suppliers, or users
Trigger	Automatic by threshold	Manual via API (/createPayout)
Destination	Your own cold wallet	Any valid blockchain address

Webhook Events

Settlement events are delivered via the same webhook system as order events:

Event	When
COLLECT_PENDING	Sweep transaction submitted to the blockchain
COLLECT_SUCCESS	Sweep transaction confirmed
COLLECT_FAILED	Sweep transaction failed

Settlement is a non-custodial process — the gateway is just software that moves funds according to your rules. At no point does any third party have access to your private keys or the ability to redirect funds. All transactions are signed locally within your Docker container.