Tutorial: Execute a quote

This tutorial shows you how to execute a quote previously received from the Liquidity Hub API to trade digital assets. You will learn about the requests and responses your integration must handle to execute a quote that specifies the price of selling 1 Bitcoin (BTC) in exchange for US Dollars (USD).

Prerequisites

The /quotes/execute endpoint is protected by Bearer authentication. To successfully call this endpoint, you must include a valid Bearer authentication token in the request header. For more information, see the Get an authentication token tutorial.
You must have the quote ID of the quote you want to execute. Your integration should process the response received from the /quotes/request endpoint and get the value of the quoteId field. For more information, see the Request a quote tutorial.
The quote you want to execute must be valid. That is, the current time must be earlier than the time specified by the expiresAt field in the quote you received from the /quotes/request endpoint.

Request body

The POST /quotes/execute operation accepts a body parameter containing the quoteId of the quote you want to execute and an optional side field.

Request body fields

The request body accepts two fields - quoteId and side. Let's take a closer look at these fields. Click to expand each section:

Quote ID

Each quote is identified is by its unique quoteId. This field is part of the Quote object returned by the /quotes/request endpoint.To execute a quote, your integration should first process the response received from the /quotes/request endpoint and get the quoteId.

Side

The side field indicates whether you want to buy or sell the baseAsset in the trade.You must specify this field only if you are executing a two-way quote, that is, if the value of the side field is TWO_WAY in the quote you received. You do not need to specify the side field if you are executing a quote where the value of the side field is BUY or SELL.In this example you are executing a quote with side = SELL, so you do not need to specify the side field.

Sample request

The following code sample makes a request to execute the quote identified by the quoteId in the request body:

Payload
curl

application/json

{"quoteId": "fd5dbe64-a96e-4e1c-9843-75cd6b0cdb60"
}

Examine the response

The code sample below shows the success response from the /quotes/execute endpoint. The Trade object in the response confirms that your request to execute a quote was successful.Let's take a closer look at some of the Trade object fields:

Field	Description
`tradeId`	The unique ID that identifies the trade. You can use this ID to retrieve this trade later for reconciliation purposes using the Retrieve a specific trade operation.
`price`	The price at which you traded one unit of `baseAsset` for the `quoteAsset`.
`baseAssetQty`	The quantity of the `baseAsset` (BTC) you sold in this trade.
`quoteAssetQty`	The quantity of the `quoteAsset` (USD) you purchased as a result of selling 1 BTC in this trade.
`timestamp`	The time at which this trade was executed.
`quoteId`	The unique ID of the quote that you executed to complete this trade.

{"tradeId": "065e2c46-be89-4fe2-9d16-ce9afeca50b7",
"price": "51345.76",
"baseAsset": "BTC",
"quoteAsset": "USD",
"baseAssetQty": "1.00000000",
"quoteAssetQty": "51345.76",
"side": "SELL",
"endUserGuid": "669ce446-22d0-11ec-9621-0242ac130002",
"timestamp": "2021-01-01T01:05:30.000Z",
"quoteId": "fd5dbe64-a96e-4e1c-9843-75cd6b0cdb60",
"fundSource": "FUNDED"
}

Error response and handling

If your request is unsuccessful, you may receive a 400, 401, 404, or 500 error code from the Liquidity Hub API.

Here are some recommendations for error handling:

Error code	Name	Recommended error handling
`400`	`Bad Request`	Your request may be missing required header or body parameters. 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.
`403`	`Forbidden`	The base URL in your request could be incorrect. Retry the request with the correct base URL.
`404`	`Not Found`	No handler found for POST
`500`	`Internal Server Error`	The service is temporarily unavailable. Retry the request later.

Next step: Check your portfolio balance

After successfully completing a trade, you can retrieve the current balance of a specific asset in your portfolio or retrieve the current balance of all assets in your portfolio.