> ## Documentation Index
> Fetch the complete documentation index at: https://docs.xpaylabs.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Settlements: Auto-Sweep Hot Wallet Funds to Cold Storage

> XPayLabs automatically sweeps received funds from hot wallets to your cold storage. Configure settlement rules and thresholds for each supported blockchain.

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              |
```

<Steps>
  <Step title="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.
  </Step>

  <Step title="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.
  </Step>

  <Step title="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.
  </Step>

  <Step title="Sweep confirmed">
    Once the transfer transaction reaches sufficient block confirmations, a `COLLECT_SUCCESS` webhook is sent. If the transaction fails, `COLLECT_FAILED` is sent.
  </Step>
</Steps>

## Configuration

You configure settlement in the gateway configuration (`.env` file or environment variables):

```yaml theme={null}
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                      |

<Note>
  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.
</Note>