Account Sweeps

An Account Sweep is a treasury management operation that consolidates balances from multiple beneficiaries and transfers them to a single destination in a batch.

This feature is essential for collecting revenue, zeroing out inactive user accounts, or pooling client funds into a primary wallet or corporate bank account.

Difference Between Account Sweeps and Cross-Border Payments

While both operations involve moving funds, they serve distinct purposes within the Caliza ecosystem:

Sweep Workflow Overview

1. Strategy: Decide whether to sweep funds from all beneficiaries or a specific subset.
2. Destination: Identify where the funds should go, such as your primary ETH (Ethereum) wallet or corporate Pix key.
3. Execute: Call the sweep endpoint to trigger the mass transfer.

Sweep Endpoint

A dedicated transaction endpoint for batch processing handles this operation.

Endpoint: POST /v1/transactions/sweep-payouts

Key Parameters

• currency: The currency code to sweep, such as USDC, USD, or BRL (Brazilian Real).
• filter: Defines the scope of the sweep.
  • ALL: Sweeps funds from every beneficiary with a positive balance in that currency.
  • SUBSET: Sweeps funds only from the beneficiaries specified in the beneficiariesSubSet list.
• beneficiariesSubSet: An array of objects containing the id and amount for each beneficiary. Include this only if the filter is set to SUBSET.
• withdrawalMethod: The payment rail used for the transfer, such as ETH for crypto, WIRE for fiat, or PIX for Brazil.
• destination: The target address. This can be a crypto wallet address, a Pix key, or a Recipient ID, depending on the withdrawal method.

Scenario A: Sweep Specific Beneficiaries

In this scenario, you want to collect specific amounts of USDC from two different users and send them to your primary Ethereum wallet.

Request Example

curl --location 'https://api.sandbox.caliza.com/core-api/v1/transactions/sweep-payouts' \
--header 'Authorization: Bearer YOUR_TOKEN' \
--header 'Content-Type: application/json' \
--data '{
    "currency": "USDC",
    "filter": "SUBSET",
    "withdrawalMethod": "ETH",
    "destination": "0xYourMasterWalletAddress123456789",
    "beneficiariesSubSet": [
        {
            "id": "BENEFICIARY_ID_1",
            "amount": 100.00
        },
        {
            "id": "BENEFICIARY_ID_2",
            "amount": 50.50
        }
    ]
}'

Expected Response

The API acknowledges the bulk operation request and returns the transaction details.

{
    "id": "SWEEP_TRANSACTION_ID",
    "currency": "USDC",
    "payoutBeneficiaryFilter": "SUBSET",
    "sweepDestination": "0xYourMasterWalletAddress123456789",
    "withdrawalMethod": "ETH"
}

Scenario B: Sweep All Funds

In this scenario, you want to zero out the USDC balance for all your beneficiaries and transfer the total amount to your corporate account via SWIFT.

Request Example

curl --location 'https://api.sandbox.caliza.com/core-api/v1/transactions/sweep-payouts' \
--header 'Authorization: Bearer YOUR_TOKEN' \
--header 'Content-Type: application/json' \
--data '{
    "currency": "USDC",
    "filter": "ALL",
    "withdrawalMethod": "SWIFT",
    "destination": "YourSwiftRecepientID"
}'

📘

When using filter: "ALL", the beneficiariesSubSet parameter isn't required. The system automatically calculates the total available balance across all your beneficiaries for the specified currency.

Expected Response

The API confirms the batch operation:

{
    "id": "SWEEP_TX_USDC_ALL_12345",
    "currency": "USDC",
    "payoutBeneficiaryFilter": "ALL",
    "sweepDestination": "YourSwiftRecipientID",
    "withdrawalMethod": "SWIFT"
}

Key differences in the response:

Monitoring Status

After initiating a sweep, monitor the transaction status using the appropriate endpoint. This allows you to track progress and confirm successful completion of the sweep operation.

Endpoint: GET /v1/transactions/{transactionId}

Request Example

curl --location 'https://api.sandbox.caliza.com/core-api/v1/transactions/SWEEP_TRANSACTION_ID' \
--header 'Authorization: Bearer YOUR_TOKEN'

Expected Response

{
    "id": "SWEEP_TRANSACTION_ID",
    "status": "SUCCEEDED",
    "integratorId": "YOUR_INTEGRATOR_ID",
    "from": {
        "currencyCode": "USDC",
        "value": 150.50
    },
    "to": {
        "currencyCode": "USDC",
        "value": 150.50
    },
    "blockchainInfo": {
        "targetWallet": {
            "address": "0xYourMasterWalletAddress123456789",
            "chain": "ETH"
        }
    },
    "createdDate": "2025-12-02T18:00:00.000Z",
    "settledAt": "2025-12-02T18:05:00.000Z"
}

Response Fields

The response includes several important fields to help you track the sweep transaction:

• status: Indicates the current state of the sweep transaction. Possible values include PENDING, PROCESSING, SUCCEEDED, or FAILED.
• from: Details the total amount swept from all beneficiaries involved in the operation.
• to: Confirms the total amount received at the destination account.
• blockchainInfo: Provides details about the blockchain transfer, including the targetWallet address and chain used (Specific to Crypto sweeps).
• createdDate: Timestamp when the sweep transaction was initiated.
• settledAt: Timestamp when the sweep transaction was completed, and funds were credited.

Related Articles