Tutorial: Request a quote

This tutorial shows you how to request a quote using the Liquidity Hub API. You will learn about the requests and responses your integration must handle to request a quote using the /quotes/request endpoint.

We use the example scenario of selling 1 Bitcoin (BTC) to buy US Dollars (USD). The quote you receive specifies the amount of USD you get in exchange for selling 1 BTC if you execute that quote.


The /quotes/request 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.

Construct the request body

The POST /quotes/request operation accepts a body parameter where you specify the details of the trade you want to execute. The operation returns a quote that you can execute to complete the trade.

In this tutorial, you want to sell 1 BTC in exchange for USD. Let's map this information to the fields in the request body:

Request quote body For more information about the side and asset quantity fields in the quote, see the Quote concept.
Quote asset value
The quoteAsset value must be USD. Requests with baseAsset = USD will result in an error response.

Sample request

The following code sample requests a quote to SELL 1 BTC in exchange for USD:
  • "baseAsset": "BTC",
  • "quoteAsset": "USD",
  • "side": "SELL",
  • "baseAssetQty": "1.00000000"

Examine the response

The code sample below shows the success response received from the /quotes/request endpoint. The Quote object in the response includes the bidPrice, that is the quantity of USD you will receive by selling 1 BTC if you execute the quote. Let's take a closer look at some of the Quote object fields:
quoteIdThe unique ID that identifies the quote. You need to specify this quoteId if you choose to execute this quote using the /quotes/execute endpoint.
bidPriceThe quantity of quoteAsset (USD) you will receive in exchange for selling 1 unit of the baseAsset (BTC).
offerPriceThis field is null because you are selling your baseAsset BTC. The offer price is specified only when the side = BUY, that is, when you want to buy the baseAsset in the trade.
quoteAssetQtyThe quantity of the quoteAsset (USD) you will receive if you execute the quote and sell 1 BTC.
expiresAtThe time at which this quote becomes invalid. You cannot execute that quote after this time.

For the full response object schema, see the Request a quote operation reference.

  • "quoteId": "fd5dbe64-a96e-4e1c-9843-75cd6b0cdb60",
  • "requestedAt": "2021-01-01T01:00:30.000Z",
  • "createdAt": "2021-01-01T01:00:32.000Z",
  • "bidPrice": "51345.76",
  • "offerPrice": null,
  • "baseAsset": "BTC",
  • "quoteAsset": "USD",
  • "baseAssetQty": "1.00000000",
  • "quoteAssetQty": "51345.76",
  • "side": "SELL",
  • "expiresAt": "2021-01-01T01:10:00.000Z",
  • "endUserGuid": "669ce446-22d0-11ec-9621-0242ac130002",
  • "fundSource": "FUNDED"

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.

Here are some recommendations for error handling:

Error codeNameRecommended error handling
400Bad RequestYour request may be missing required header or body parameters. Inspect your request and retry the request.
401UnauthorizedYour 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.
403ForbiddenThe base URL in your request could be incorrect. Retry the request with the correct base URL.
404Not FoundNo handler found for POST
500Internal Server ErrorThe service is temporarily unavailable. Retry the request later.

Next step: Execute the quote

Since every quote is valid for a limited time (specified by the expiresAt field in the response body), your integration should be able to quickly decide whether to execute a quote or not. As a best practice, specify price thresholds that the integration can compare the bidPrice or offerPrice against and decide whether the quote should be executed.If the price specified in the quote you received meets the criteria for completing the trade, your integration should call the /quotes/execute endpoint to execute the quote. See the Execute a quote guide for more details.