Guides

Send Withdrawals

Create a transaction to withdraw crypto from your asset pool and send it to an external wallet.

Suggest Edits

This guide outlines the process for integrating withdrawals into your platform. It provides a detailed walkthrough of the withdrawal process, including how it interacts with the respective blockchain, which endpoint is used to create the payout, the data that needs to be sent to the endpoint, and what that data represents. Additionally, it covers the webhooks sent out during the withdrawal process.

To integrate the withdrawal feature, you must complete the following steps:

  1. Set up the webhooks destination to send update notifications and any other related events. The webhooks you need are the following:
    • layer1:crypto:withdrawal:status-change
    • layer1:digital:balance:updated
  2. Create the asset pool that will house the created address and keep track of all funds sent to any related addresses created in future.
  3. Ensure that funds are available in the asset pool to withdraw. For the details, refer to the Create a new address and Receive Deposit and Ingest the Webhooks guides.

To summarise, the withdrawal process involves the following:

  1. Creating a Withdrawal Transaction via the Create transaction request endpoint. The outbound wallet address is sent in the request.
  2. Ingesting and deserialising the resulting webhooks to keep track of your pool funds and the status of the withdrawal.

Withdrawal Flow

The withdrawals pass through the following lifecycle on the Layer1 platform:

  1. A new transaction request is registered with status CREATED and type WITHDRAWAL.
  2. The system checks whether the asset pool contains sufficient funds for the requested withdrawal.
    1. If there are insufficient funds, the withdrawal’s status becomes REJECTED (final).
    2. If there are sufficient funds, the process moves on to reserve those funds.
  3. During funds reservation, the required amount is moved from the available balance to the reserved balance of the source addresses. The status is updated to FUNDS_RESERVED.
  4. Once funds are reserved, the transaction is flagged for compliance screening. The status becomes SCREENING_REQUESTED.
  5. The transaction undergoes automated screening:
    1. If it passes, the status becomes SCREENING_PASSED.
    2. If it fails, the status becomes HELD.
  6. Transactions in HELD are subject to manual review:
    1. If manually approved, the status changes to SCREENING_PASSED.
    2. If rejected, the status becomes REJECTED (final).
  7. After the screening is passed, the system assembles and signs the WITHDRAWAL. It becomes ready for blockchain submission. The state updates to SIGNED.
  8. The signed transaction is submitted to the blockchain; once detected by monitoring logic, its status becomes DETECTED.
  9. The respective blockchain processes the transaction and includes it in a new block. This blockchain transaction may contain errors if it is unsuccessful.
    1. If execution fails (irreversible), status becomes FAILED (final). This action is irreversible.
    2. If execution succeeds, status becomes UNCONFIRMED. The transaction is monitored until it reaches the required confirmation threshold. For more information, see confirmation threshold.
  10. After the required number of confirmations is reached, the status updates to CONFIRMED.
  11. The reserved funds are released and available balance is updated to reflect the irrevocable blockchain fund movement. The WITHDRAWAL is now finalised and state is set to SUCCESS.

Withdrawal Status

A Withdrawal goes through a series of statuses, with each status denoting a specific process has occurred:

StatusDescription
CreatedThe withdrawal request is first registered with the created status
RejectedThe withdrawal is rejected if there are insufficient funds within the asset pool to action the withdrawal
Funds_ReservedThe withdrawal has moved funds from the available balance to the reserved balance
Screening_RequestedThe withdrawal has moved into the screening phase and needs to be screened
HeldThe withdrawal has been held to be manually reviewed
Screening_PassedThe withdrawal has passed screening, either manual or automatic
SignedThe withdrawal is signed and submitted to the blockchain
DetectedThe withdrawal has been detected and distributed on the blockchain, but does not yet have any confirmations
FailedThe withdrawal failed due to an on-chain error has occurred during execution, could be multiple underlying reasons
UnconfirmedThe withdrawal has had one or more blockchain confirmations, but has not yet reached the required confirmation limit
ConfirmedThe withdrawal has reached the required confirmation limit and is not fully confirmed on the blockchain
SuccessThe withdrawal is successful and the balance of the asset pool is updated to reflect this

Updated 10 days ago