Tutorial: Request a crypto asset withdrawal

This tutorial shows you how to create a request to withdraw crypto assets from your Liquidity Hub account into your wallet using the Liquidity Hub API.

Withdrawing a crypto asset is a two-step process:

Send the withdrawal request by calling the POST /withdraw-crypto API operation.
Examine the response to determine the request status.

We use the example of creating a request to withdraw a specific quantity of Bitcoin (BTC) from your Liquidity Hub account into your wallet.

Prerequisites

Authentication: The POST /withdraw-crypto operation is protected by Bearer authentication. To successfully call this operation, you must include a valid Bearer authentication token in the request header. For more information, see the Get an authentication token tutorial.
Validated wallet: You should have at least one validated wallet that can store the type of crypto asset you are withdrawing. A validated wallet is a wallet that has completed the Know Your Customer (KYC) process and other checks required by Ripple.

Send the withdrawal request

Call the POST /withdraw-crypto operation to create the request to withdraw BTC from your Liquidity Hub account.

Construct the request body

To successfully call the POST /withdraw-crypto operation, you must include the body parameter where you specify the symbol of the asset you want to withdraw, the quantity of the asset you want to withdraw, and the destination wallet address where you want to receive the withdrawn asset.

In this tutorial, you will withdraw 1.00000001 BTC from your account. Let's map this information to the fields in the request body:

Sample request

The following code sample shows the API call to request a withdrawal of 1.00000001 BTC from your Liquidity Hub account into the wallet address you specified:

Payload
curl

application/json

{"asset": "BTC",
"walletAddress": "3a98b1AbCD73EFaBcdefghijKabcDeFGHi",
"assetQty": "1.00000001"
}

Examine the response

The following code sample shows the response body received with the 200 OK status response code. success response received from the /withdraw-crypto endpoint.

Note: The value of the withdrawalStatus field represents the status of the withdrawal request itself, and not whether the request for withdrawal was placed successfully. The 200 OK response code indicates that the request was placed successfully.

{"transactionId": "abcdefgh-abcd-abcd-1234-1234abcdefgh",
"withdrawalStatus": "PENDING"
}

For the full response schema, see the Withdraw crypto asset from your account operation reference.

Error responses and handling

If your request is unsuccessful, you may receive a 400, 401, 404, or 500 error code from the Liquidity Hub API. The following table provides more details about these errors:

Error code	Name	Possible cause and error handling
`400`	`Bad Request`	Your request may be missing required header or path parameters, or there may be a problem with one or more of the values specified in the request body. This error code is returned in cases where: The wallet address you specified in the request has not been validated yet. You specified an unsupported crypto asset. The withdrawal amount you requested is higher than the balance in your account. Inspect your request and retry the request.
`401`	`Unauthorized`	Your Bearer authentication token may be invalid or expired. Verify that the authentication token is not truncated or past the token expiry period. Retry the request again with a valid authentication token.
`404`	`Not Found`	The resource was not found.
`500`	`Internal Server Error`	The service is temporarily unavailable. Retry the request later.

Next steps

Check the Transfers page in the Liquidity Hub UI for updates on your request status. Identify the withdrawal on the Transfers page by looking for the transactionId that you received in the response. The ID appears in the Transfer ID column in the UI.

After the transfer is complete, you can: