Quick start guide

Trading one digital asset for another is one of the most frequent operations you will perform using the Liquidity Hub API.

This guide walks you through the three-step process of buying one Bitcoin (BTC) in exchange for US Dollars (USD):

  1. Request an authentication token to access secured Liquidity Hub API endpoints.
  2. Request a quote to get the price at which you can buy one BTC in exchange for USD.
  3. After reviewing the quote, execute the quote to buy one BTC at the quoted price.
Base URL for the sandbox environment
If you are performing the API calls in this tutorial in the Liquidity Hub API sandbox environment, use https://liquidity-hub.uat.prod.ripplenet.com/api/v0 as the base URL.

Request an authentication token

You must include a valid Bearer authentication token in your request header when you send requests to secured Liquidity Hub API endpoints. To get a Bearer authentication token, send a POST request to the /oauth/token endpoint.

Prerequisites

You must have your client ID and client secret to get an authentication token.

Request format

Specify your clientId and clientSecret in the request body as shown in the example below.
application/json
{
  • "clientId": "vTRUNYZoYuk0zsQq1Bs09lliKKriqWNn",
  • "clientSecret": "wwkNBXm_y2cqYSVdNkhfCcYhbsyczx4c1RfSX8MmOuJwdT1_9ejPXFVFIK0cH1w3"
}

For the full request object schema, see the Request Auth Token operation reference.

Response format

The response contains the authentication token in the accessToken field as shown in the example below.
{
  • "accessToken": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c",
  • "expiresIn": 300,
  • "tokenType": "Bearer",
  • "scope": "resource_one:read resource_one:write resource_two:read"
}
For the AuthToken object schema, see the Request Auth Token operation reference.

Request a quote

Send a POST request to the /quotes/request endpoint with a request body that contains details of the digital asset you want to buy or sell. The response contains the price at which you can buy one BTC in exchange for USD.

Request format

Using the following example you request a quote to buy one unit of BTC in exchange for USD.

application/json
{
  • "baseAsset": "BTC",
  • "quoteAsset": "USD",
  • "side": "BUY",
  • "baseAssetQty": "1.00000000"
}
For more information about the side parameter, see Quote. For the full request object schema, see the Request a quote operation reference.
Quote asset value
The quoteAsset value must be USD. Requests with baseAsset = USD will result in an error response.

Response format

The offerPrice value in the response is the quantity of USD you have to pay to purchase one BTC. This quote is uniquely identified by the quoteId.
{
  • "quoteId": "fd5dbe64-a96e-4e1c-9843-75cd6b0cdb60",
  • "requestedAt": "2021-01-01T01:00:30.000Z",
  • "createdAt": "2021-01-01T01:00:32.000Z",
  • "bidPrice": null,
  • "offerPrice": "62289.42",
  • "baseAsset": "BTC",
  • "quoteAsset": "USD",
  • "baseAssetQty": "1.00000000",
  • "quoteAssetQty": "62289.42",
  • "side": "BUY",
  • "expiresAt": "2021-01-01T01:10:00.000Z",
  • "endUserGuid": "669ce446-22d0-11ec-9621-0242ac130002",
  • "fundSource": "FUNDED"
}

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

Execute the quote

When you execute a quote, you buy your baseAsset (BTC) in exchange for the quoteAsset (USD) at the quoted price. The quoted price is the offerPrice value in the quote. Execute the quote by sending a POST request to the /quotes/execute endpoint.

Request format

You must include the quoteId field in the request body to execute the quote. You can find the quoteId in the response returned by the /quotes/request .

Here is the example request body:

application/json
{
  • "quoteId": "fd5dbe64-a96e-4e1c-9843-75cd6b0cdb60"
}

For the full request object schema, see the Execute a specific quote operation reference.

Response format

The response contains a Trade object with a unique tradeId and other information about the trade. This indicates that the trade is now complete and your portfolio is up-to-date with your latest digital asset holdings.The following example shows a success response from the /quotes/execute endpoint:
{
  • "tradeId": "065e2c46-be89-4fe2-9d16-ce9afeca50b7",
  • "price": "62289.42",
  • "baseAsset": "BTC",
  • "quoteAsset": "USD",
  • "baseAssetQty": "1.00000000",
  • "quoteAssetQty": "62289.42",
  • "side": "BUY",
  • "endUserGuid": "669ce446-22d0-11ec-9621-0242ac130002",
  • "timestamp": "2021-01-01T01:05:30.000Z",
  • "quoteId": "fd5dbe64-a96e-4e1c-9843-75cd6b0cdb60",
  • "fundSource": "FUNDED"
}
For the Trade object schema, see the Execute a specific quote operation reference.
Success

You have successfully bought one BTC in exchange for USD!

Next steps

Explore other Liquidity Hub API operations: