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

GET /v1/wallets/{wallet_id}/actions/{action_id}

Add ?include=steps to the request to see step-level status details for debugging.

Or subscribe to webhooks to receive push notifications when the transfer reaches a terminal state.

Embedded wallets

Management

Usage

UI components

Custodial wallets

Global wallets

EVM smart wallets

Action-level status

Step-level status

Typical flow

Tracking status

Next steps

Transfer webhooks

Authorization controls

​Action-level status

​Step-level status

​Typical flow

​Tracking status

​Next steps

Transfer webhooks

Authorization controls

Action-level status

Step-level status

Typical flow

Tracking status

Next steps