How to sweep token balances to treasury

Prerequisites

If your target chain does not support sponsored transfers (e.g. Bitcoin, Cosmos, TON), see the Non-sponsored chains section at the bottom of this page.

Overview of the sequence

1. Query balances for the target asset across all wallets (single call)
2. Filter: remove zero-balance, below-threshold, destination, and sponsor wallets
3. Initiate one sponsored transfer per eligible wallet
4. Track each transaction to CONFIRMED

Step 1 — Query balances for the target asset

Use the wildcard wallet ID (-) to query a specific asset's balance across every wallet in the vault in a single call. This avoids N+1 requests.

POST /v2/vaults/{vault_id}/wallets/-:queryBalances

{
  "filter": "asset(\"assets/erc20.polygon-mainnet.0x3c499c542cef5e3811e1192ce70d8cc03d5c3359\")"
}

Response:

{
  "balances": [
    {
      "asset": "assets/erc20.polygon-mainnet.0x3c499c542cef5e3811e1192ce70d8cc03d5c3359",
      "wallet": "vaults/abc123/wallets/w001",
      "value": "15.00",
      "rawValue": "15000000",
      "usdValue": "15.00"
    },
    {
      "asset": "assets/erc20.polygon-mainnet.0x3c499c542cef5e3811e1192ce70d8cc03d5c3359",
      "wallet": "vaults/abc123/wallets/w002",
      "value": "0.50",
      "rawValue": "500000",
      "usdValue": "0.50"
    }
  ]
}

No filter: Omit the filter body entirely to get all asset balances across all wallets in one call. Useful if you're sweeping multiple assets or want a full balance snapshot first.

Pagination: Default page size is 50. Use pageSize=1000 (max) and follow nextPageToken to iterate all results.

Amount fields:

Use value when building your eligible wallet list and when passing amount to InitiateTransaction.

Step 2 - Filter eligible wallets

From the balance results, build the list of wallets to sweep. Apply these filters in order:

1. Balance > 0 - skip wallets with no holdings of the target asset
2. Threshold (optional) - only sweep wallets above a minimum value to avoid dust
3. Frozen balance - if frozenValue > 0, sweep only the non-frozen portion (value minus frozenValue); skip entirely if nothing is available
4. Exclude the destination wallet - don't sweep funds from the treasury to itself
5. Exclude the sponsor wallet - don't sweep the gas wallet

You don't need to resolve blockchain addresses separately. The wallet resource name (vaults/{vault_id}/wallets/{wallet_id}) works directly as source in the next step.

Step 3 - Initiate sponsored transfers

For each eligible wallet, call InitiateTransaction with the sponsor field set to your gas wallet.

POST /v2/vaults/{vault_id}/transactions:initiate

{
  "details": {
    "assetTransfer": {
      "asset": "assets/erc20.polygon-mainnet.0x3c499c542cef5e3811e1192ce70d8cc03d5c3359",
      "amount": "15.00",
      "source": "vaults/abc123/wallets/w001",
      "destination": "vaults/abc123/wallets/treasury",
      "sponsor": "vaults/abc123/wallets/gas-sponsor"
    }
  }
}

When sponsor is set, the source wallet needs no native gas tokens - only the asset being transferred.

Repeat for each eligible wallet, substituting source and amount from your filtered results. Each call returns immediately with state: CREATED; transactions are processed asynchronously.

If one wallet fails, continue with the rest - log the error and the wallet ID, don't abort the sweep.

Field reference

asset - Full asset resource name with assets/ prefix.

amount - Human-readable units. Pass the value field from the balance response directly.

"amount": "15.00"   ← 15.00 USDC
"amount": "0.50"    ← 0.50 USDC

source and destination - three accepted formats:

Wallet resource name is recommended - it avoids having to resolve addresses separately and works across networks.

sponsor - wallet resource name of the gas wallet:

"sponsor": "vaults/{vault_id}/wallets/{sponsor_wallet_id}"

EVM - delegation prerequisite

On EVM chains, if a source wallet has not previously delegated to Utila's EIP-7702 contract, a single InitiateTransaction call may produce two transactions: a delegation transaction (EVM_ACCOUNT_DELEGATION) followed by the transfer. Both are returned in the response. Track both IDs and wait for the delegation to reach CONFIRMED before the transfer can execute.

Supported chains

Sponsored transfers (sponsor on assetTransfer) are supported on:

Sponsorship must be enabled for your vault on the target chain. If InitiateTransaction rejects a request that includes sponsor, contact Utila Support to enable sponsored transfers for that chain.

Step 4 - Track results

Each InitiateTransaction call returns a transaction resource name. Collect all of them.

GET /v2/vaults/{vault_id}/transactions/{transaction_id}

Happy path:

AWAITING_POLICY_CHECK → AWAITING_SIGNATURE → SIGNED → AWAITING_PUBLISH → PUBLISHED → MINED → CONFIRMED

Policy-gated vaults may include AWAITING_APPROVAL before signing.

Failure and end states:

For production sweeps, subscribe to webhooks (TRANSACTION_STATE_UPDATED) instead of polling each transaction individually.

Error handling

Common asset IDs

Full asset names use the assets/ prefix: assets/erc20.polygon-mainnet.0x3c49...

Non-sponsored chains

For chains that don't support the sponsor parameter (Bitcoin, Cosmos, TON), use a three-step gas pre-funding flow.

1. Estimate gas per wallet

POST /v2/vaults/{vault_id}/transactions:estimateFee

Same body structure as InitiateTransaction - details.assetTransfer with asset, amount, source, destination, no sponsor.

2. Send native gas to each source wallet

Use the estimated fee plus a 10–20% buffer as amount:

{
  "details": {
    "assetTransfer": {
      "asset": "assets/native.{network}",
      "amount": "{estimated_gas_with_buffer}",
      "source": "vaults/{vault_id}/wallets/{gas_wallet_id}",
      "destination": "vaults/{vault_id}/wallets/{source_wallet_id}"
    }
  }
}

Wait for this transfer to reach CONFIRMED before proceeding. If you initiate the asset transfer before gas arrives on-chain, it will fail.

3. Initiate the asset transfer

Same as Step 3 above, without the sponsor field.

Fee estimate staleness: Network fees fluctuate. If significant time passes between your estimateFee call and the gas top-up, or between the top-up and the asset transfer, the actual fee at execution may exceed your estimate. Run estimate → gas top-up → asset transfer as a tight sequence per wallet, and add a buffer.

Bitcoin: Use wallet resource names for source and destination - raw addresses are not supported as source.