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

# Transfer lifecycle

After initiating a transfer from a custodial wallet via `POST /v1/wallets/{wallet_id}/transfer`, the transfer is represented as a [wallet action](/wallets/actions/overview) with a `custodian_transaction` step. The custodian (e.g. Bridge) must conduct transaction screening and compliance checks before the transaction is executed on-chain.

## Action-level status

The top-level wallet action status reflects the overall outcome:

| Status      | Description                                                                                                              |
| ----------- | ------------------------------------------------------------------------------------------------------------------------ |
| `pending`   | The transfer is in progress — the custodian is reviewing or executing it.                                                |
| `succeeded` | The transfer has been confirmed on-chain (terminal).                                                                     |
| `rejected`  | The transfer was rejected before any on-chain effect, e.g. due to custodian compliance checks (terminal). Safe to retry. |
| `failed`    | The transfer failed after being initiated on-chain (terminal). May have partial on-chain effects.                        |

## Step-level status

For custodial transfers, the wallet action has a single step of type `custodian_transaction`. The step status provides more granular detail about where the transfer is in its lifecycle:

| Step status           | Description                                                                                                                |
| --------------------- | -------------------------------------------------------------------------------------------------------------------------- |
| `preparing`           | The transfer request is being prepared and validated.                                                                      |
| `queued`              | The transfer is queued, waiting for a prior step to complete.                                                              |
| `custodian_reviewing` | The custodian is conducting compliance screening and approval checks. The transaction has not yet been initiated on-chain. |
| `pending`             | The custodian has approved and initiated the transaction. It is now pending confirmation on the blockchain.                |
| `confirmed`           | The transaction has been confirmed on-chain (terminal, success).                                                           |
| `rejected`            | The custodian rejected the transfer during review (terminal, failure).                                                     |
| `failed`              | The transaction failed after being initiated (terminal, failure).                                                          |

## Typical flow

```
preparing → custodian_reviewing → pending → confirmed
```

If the custodian rejects the transfer during review, the step transitions directly to `rejected`:

```
preparing → custodian_reviewing → rejected
```

## Tracking status

Use the wallet action ID returned from the transfer request to poll for status:

```bash theme={"system"}
GET /v1/wallets/{wallet_id}/actions/{action_id}
```

<Tip>Add `?include=steps` to the request to see step-level status details for debugging.</Tip>

Or subscribe to [webhooks](/wallets/custodial-wallets/advanced/webhooks) to receive push notifications when the transfer reaches a terminal state.

## Next steps

<CardGroup>
  <Card title="Transfer webhooks" icon="webhook" href="/wallets/custodial-wallets/advanced/webhooks">
    Monitor transfer status and lifecycle events
  </Card>

  <Card title="Authorization controls" icon="shield-halved" href="/wallets/custodial-wallets/advanced/authorization-controls">
    Configure policies and multi-party approvals for custodial wallets
  </Card>
</CardGroup>