Send Withdrawals

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
   • layer1:approval:request:vote-required only if using approvals
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 if the asset pool has sufficient funds to process the withdrawal:

   a. If sufficient funds are available:

   • The transaction proceeds to reserve the funds.

   b. If funds are insufficient:

   • Status updates to FUNDS_NEEDED Two outcomes are possible while in FUNDS_NEEDED

   • Liquidity becomes available:

     • The transaction automatically retries once matching funds are detected.
     • No manual action is needed if the new liquidity matches the transaction's pool, network, and asset.
     • Liquidity can come from:
       • New deposits
       • Internal consolidations
       • Manual top-ups by your team

   • Timeout expires (after 24 hours):

     • The transaction is automatically rejected.
     • Status updates to REJECTED

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 reviewed against approval rules (i.e. requires approval for any withdrawal over $10,000).

   1. If approval is required, the status changes to APPROVAL_REQUESTED
   2. If no approval is required, the transaction moves to compliance screening. The status becomes SCREENING_REQUESTED.

5. The transaction then undergoes automated screening:

   1. If it passes, the status becomes SCREENING_PASSED.
   2. If it fails, the status becomes HELD.
   3. If it fails because the destination is a sanctioned blockchain address, the status becomes REJECTED (final)

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 has been updated 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), the 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 the 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 can go through a series of statuses, with each status denoting a specific process has occurred: