Settlements: Auto-Sweep Hot Wallet Funds to Cold Storage

Settlement 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 on a T+2 schedule, XPayLabs settlement is a blockchain-native process — funds move directly between your wallets on-chain within minutes, not days.

How does settlement work?

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

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.

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.

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.

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 configuration (.env file or environment variables):

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.

Get Started

Core Concepts

Guides

x402 Protocol

Support

Settlements: Auto-Sweep Hot Wallet Funds to Cold Storage

How does settlement work?

Configuration

Settlement vs. Payout

Webhook Events

​How does settlement work?

​Configuration

​Settlement vs. Payout

​Webhook Events

How does settlement work?

Configuration

Settlement vs. Payout

Webhook Events