# Trigger asset sweeps via the API

Use the Ripple Custody (Wallet) API to run an existing sweep configuration on demand and to find the transactions that sweeps create. To set up and monitor sweeps in the console, see [Configure asset sweeping](/pt-br/products/wallet/vaults-and-wallets/asset-sweeping/configure-asset-sweeping).

## Sweep actions

| Action | Console role | Console procedure | API procedure |
|  --- | --- | --- | --- |
| Enable source wallets | Owner, Administrator, Proposer | [Enable source wallets](/pt-br/products/wallet/vaults-and-wallets/asset-sweeping/configure-asset-sweeping#enable-source-wallets-via-the-console) | [Update wallet settings](/pt-br/products/wallet/vaults-and-wallets/wallets/manage-wallets-api#update-wallet-settings-via-the-api) |
| Create a sweep configuration | Owner, Administrator | [Create a sweep configuration](/pt-br/products/wallet/vaults-and-wallets/asset-sweeping/configure-asset-sweeping#create-a-sweep-configuration-via-the-console) | - |
| Enable or disable a sweep | Owner, Administrator | [Enable or disable a sweep](/pt-br/products/wallet/vaults-and-wallets/asset-sweeping/configure-asset-sweeping#enable-or-disable-a-sweep-via-the-console) | - |
| Run a sweep now | Owner, Administrator | [Run a manual sweep](/pt-br/products/wallet/vaults-and-wallets/asset-sweeping/configure-asset-sweeping#run-a-manual-sweep-via-the-console) | [Trigger a sweep](#trigger-a-sweep-via-the-api) |
| Update a sweep | Owner, Administrator | [Update a sweep](/pt-br/products/wallet/vaults-and-wallets/asset-sweeping/configure-asset-sweeping#update-a-sweep-via-the-console) | - |
| Delete a sweep | Owner, Administrator | [Delete a sweep](/pt-br/products/wallet/vaults-and-wallets/asset-sweeping/configure-asset-sweeping#delete-a-sweep-via-the-console) | - |
| Monitor sweep runs | Owner, Administrator, Auditor | [Monitor sweep runs](/pt-br/products/wallet/vaults-and-wallets/asset-sweeping/configure-asset-sweeping#monitor-sweep-runs-via-the-console) | [Find sweep transactions](#find-sweep-transactions-via-the-api) |


**Permissions:** In the console, owners and administrators can create, update, and delete sweep configurations (workflows), and owners, administrators, and auditors can view them. Owners, administrators, and proposers can enable sweeping on a wallet. See [User roles and permissions](/pt-br/products/wallet/organization-and-access/users-and-roles#asset-sweeping-workflows). Triggering a sweep and finding its transactions need an API credential of type `TRANSACTIONS`. Enabling sweeping on a wallet through the API needs a `WALLETS` credential.

## Prerequisites

- **An API credential of type `TRANSACTIONS`.** Its grantable permissions cover creating and managing transactions and triggering sweeps. Create credentials in the console. See [Manage API credentials](/pt-br/products/wallet/organization-and-access/api-credentials/manage-api-credentials) and [Credential types](/pt-br/products/wallet/organization-and-access/api-credentials#credential-types).
- **An access token.** Exchange your credential's `clientId` and `clientSecret` for a bearer token. See [Getting started with the API](/pt-br/products/wallet/get-started/use-the-api#step-2-authenticate).
- **An existing sweep configuration and its ID.** You create and change sweep configurations in the console only; the API can trigger a configuration that already exists but can't create, list, or update one. To get the ID, copy it from the **ID** column of the sweep list in **Settings** > **Workflows**, or from the configuration's details page. See [Create a sweep configuration](/pt-br/products/wallet/vaults-and-wallets/asset-sweeping/configure-asset-sweeping#create-a-sweep-configuration-via-the-console).
- **Source wallets enabled for sweeping.** Each source wallet needs **Sweeping** and **Outgoing transactions** turned on. Through the API, these are the `sweepingEnabled` and `enabled` wallet settings. See [Update wallet settings](/pt-br/products/wallet/vaults-and-wallets/wallets/manage-wallets-api#update-wallet-settings-via-the-api).


For the base URLs, token lifetime, pagination, filtering, and error format that every endpoint shares, see [API conventions](/pt-br/products/wallet/api-and-developer-experience/api-conventions).

## Trigger a sweep via the API

**API reference:** [Trigger a sweep configuration](/pt-br/products/wallet/api-docs/palisade-api/palisade-api/sweep-configurations/sweepservice_triggersweepconfiguration)

Send a `POST` request to `/v2/workflows/sweep/{id}/trigger`, where `id` is the ID of the sweep configuration. This runs the configuration immediately, outside its hourly or daily schedule, like **Manual sweep** in the console. The request takes no body.

```bash
curl -X POST "https://api.sandbox.palisade.co/v2/workflows/sweep/$SWEEP_CONFIGURATION_ID/trigger" \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

A successful trigger returns an empty JSON object:

```json
{}
```

Check the configuration ID
Use the ID of an existing sweep configuration from **Settings** > **Workflows**. If a sweep for the configuration is already running, the trigger returns HTTP `400` with the message `sweep configuration already running` and reason `PAL017.006`: wait for the run to finish.

The sweep runs asynchronously. Each run creates a **sweep instance**, which creates a transaction for each eligible source wallet and asset, moving funds to the configuration's deposit wallet. Sweep transactions bypass transaction policies, then go through signing and publishing like any other transaction. See [How source wallets work](/pt-br/products/wallet/vaults-and-wallets/asset-sweeping#how-source-wallets-work) and [How transactions work](/pt-br/products/wallet/transactions).

## Find sweep transactions via the API

The trigger response doesn't include the ID of the sweep instance it started, and the API has no endpoint that lists sweep instances. To find the transactions a sweep created, use one of these methods.

### List all sweep transactions via the API

**API reference:** [List transactions](/pt-br/products/wallet/api-docs/palisade-api/palisade-api/transactions/transactionsservice_listtransactions)

Send a `GET` request to `/v2/transactions` and filter by the `PALISADE_SWEEP` transaction type. The `filter.type` parameter matches each transaction's `action` field. Add a time filter to narrow the results to the run you triggered.

```bash
curl "https://api.sandbox.palisade.co/v2/transactions?filter.type.eq=PALISADE_SWEEP&filter.createdAt.after=2026-07-23T10:20:00Z&pagination.orderBy=created_at&pagination.order=SORT_ORDER_DESC" \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

The response has the same shape as the sweep instance response below. Sweep transactions have `action` set to `PALISADE_SWEEP` and `originContext.type` set to `TYPE_SWEEP`.

### List transactions for a sweep instance via the API

**API reference:** [List transactions for a sweep instance](/pt-br/products/wallet/api-docs/palisade-api/palisade-api/transactions-sweep/transactionsservice_listsweepinstancetransactions), [List transactions for a sweep instance with a request body](/pt-br/products/wallet/api-docs/palisade-api/palisade-api/transactions-sweep/transactionsservice_listsweepinstancetransactions2)

If you have a sweep instance ID from the console's sweep run history (see [Monitor sweep runs](/pt-br/products/wallet/vaults-and-wallets/asset-sweeping/configure-asset-sweeping#monitor-sweep-runs-via-the-console)), send a `GET` request to `/v2/transactions/sweep/{sweepId}`, where `sweepId` is the sweep instance ID. An ID that doesn't match a sweep instance returns HTTP `200` with an empty `transactions` array. The endpoint accepts:

- `pagination.pageSize` (default 50, maximum 1,000) and `pagination.pageToken`.
- `pagination.orderBy` (`created_at`, `updated_at`, `amount`, or `status`) and `pagination.order` (`SORT_ORDER_ASC` or `SORT_ORDER_DESC`).
- `correlationId`: an optional identifier to correlate this request with related actions.


```bash
curl "https://api.sandbox.palisade.co/v2/transactions/sweep/$SWEEP_INSTANCE_ID?pagination.pageSize=50" \
  -H "Authorization: Bearer $ACCESS_TOKEN"
```

The response contains the transactions that the sweep run created:

```json
{
  "filter": {
    "total": 1
  },
  "transactions": [
    {
      "id": "1d6f7a52-8c3e-4b09-9a41-2f6a0c1e9b77",
      "walletId": "3b8e2c14-5f6d-4a1b-8c2e-9d0f1a2b3c4d",
      "vaultId": "9a7b6c5d-4e3f-2a1b-0c9d-8e7f6a5b4c3d",
      "createdBy": "9b1deb4d-3b7d-4bad-9bdd-2b0d7b3dcb6d",
      "createdAt": "2026-07-23T10:22:22.420Z",
      "updatedAt": "2026-07-23T10:24:51.007Z",
      "status": "CONFIRMED",
      "action": "PALISADE_SWEEP",
      "originContext": { "type": "TYPE_SWEEP" },
      "blockchain": "XRP_LEDGER",
      "asset": {
        "id": "3::XRP",
        "standard": "NATIVE",
        "symbol": "XRP",
        "name": "XRP",
        "blockchain": "XRP_LEDGER",
        "decimals": 6,
        "createdAt": "2024-01-01T00:00:00.000Z"
      },
      "feeAsset": {
        "id": "3::XRP",
        "standard": "NATIVE",
        "symbol": "XRP",
        "name": "XRP",
        "blockchain": "XRP_LEDGER",
        "decimals": 6,
        "createdAt": "2024-01-01T00:00:00.000Z"
      },
      "origin": {
        "type": "WALLET",
        "id": "3b8e2c14-5f6d-4a1b-8c2e-9d0f1a2b3c4d",
        "vaultId": "9a7b6c5d-4e3f-2a1b-0c9d-8e7f6a5b4c3d",
        "address": "rPT1Sjq2YGrBMTttX4GZHjKu9dyfzbpAYe"
      },
      "originAddress": "rPT1Sjq2YGrBMTttX4GZHjKu9dyfzbpAYe",
      "destination": {
        "type": "WALLET",
        "id": "6e2a9c41-0b7d-4f3e-a8c5-1d9e2f4b7a60",
        "vaultId": "ce4918bf-a199-4ce2-85a3-d0d296855384",
        "address": "rN7n7otQDd6FczFgLdSqtcsAUxDkw6fzRH"
      },
      "qty": "125.5",
      "signOnly": false,
      "freezeInfo": { "isFrozen": false }
    }
  ]
}
```

For complex queries, send the same pagination options as a JSON body in a `POST` request to `/v2/transactions/sweep/{sweepId}:list`.

## Check the results

Check each transaction's `status` to confirm the swept funds arrived. If a sweep transaction ends in `REJECTED` or `FAILED`, inspect its `problems` array for structured failure details. If a wallet wasn't swept at all, check its settings, its available balance against the minimum sweep amount, and the fee wallet's native asset balance. See [Troubleshooting](/pt-br/products/wallet/vaults-and-wallets/asset-sweeping/configure-asset-sweeping#troubleshooting).

Read contract-token transfers carefully
For a contract-token sweep, once the transaction reaches `COMPILED`, the top-level `destination` is the token contract, `qty` is typically `"0"`, and `asset` is the blockchain's native asset. Read the `TRANSFER` entry in `proposedAssetChanges` or `confirmedAssetChanges` for the recipient and amount. See [Reading contract-token transfer fields](/pt-br/products/wallet/transactions/view-and-track-transactions#read-contract-token-transfers-via-the-api).

## Errors

Failed requests return an HTTP error status and an error object with `code`, `message`, and `details` fields. See [Error codes](/pt-br/products/wallet/api-and-developer-experience/error-codes). For the causes of and fixes for the errors these endpoints return, see [Troubleshoot common errors](/pt-br/products/wallet/api-and-developer-experience/error-codes#troubleshoot-common-errors).

## Next steps

- [Configure asset sweeping](/pt-br/products/wallet/vaults-and-wallets/asset-sweeping/configure-asset-sweeping): create, update, and monitor sweep configurations in the console.
- [Ripple Custody (Wallet) API reference](/pt-br/products/wallet/api-docs/palisade-api/palisade-api): the full request and response schemas.