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 typecustodian_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
rejected:
Tracking status
Use the wallet action ID returned from the transfer request to poll for status:Next steps
Transfer webhooks
Monitor transfer status and lifecycle events
Authorization controls
Configure policies and multi-party approvals for custodial wallets