Get asset and portfolio balances

This tutorial shows you how to use the Liquidity Hub API to get balances of the digital assets in a customer's portfolio.

You will learn about the requests and responses your integration must handle to:

Get the balance of a specific digital asset in a customer's portfolio using the /balances/{asset} API endpoint. This tutorial uses the example of getting the balance of the digital asset Ether (ETH) in a customer's portfolio.
Get the balances of all digital assets in a customer's portfolio using the /balances API endpoint.

Prerequisites

Both the GET /balances/{asset} and GET /balances operations are protected by Bearer authentication. To successfully call these operations, you must include a valid Bearer authentication token in the request header. For more information, see the Get an authentication token tutorial.

Get the balance of a specific digital asset

In this tutorial, you request the balance of ETH in a customer's digital asset portfolio in Liquidity Hub.

Construct the request

The GET /balances/{asset} operation accepts the asset path parameter. The valid value of this parameter is the symbol of the digital asset whose balance you want to get. To get the balance of Ether in a customer's portfolio, specify the value of the asset parameter as ETH.

Sample request

The following code sample requests the balance of ETH in a customer's digital asset portfolio:

curl

Examine the response

The following code sample shows the success response received from the /balances/{asset} endpoint.

{"asset": "ETH",
"total": "13.06919226",
"available": "13.00000000",
"reserved": "0.06919226",
"lastUpdated": "2021-01-01T01:00:30.000Z",
"endUserGuid": "669ce446-22d0-11ec-9621-0242ac130002"
}

The above response from the /balances/{asset} endpoint contains the Balance object. This object specifies the balance of the digital asset in the customer's portfolio. Let's take a closer look at the key fields in the Balance object:

Field	Description
`asset`	The symbol of the digital asset whose balance is returned. In this example, the balance is returned for `ETH`.
`total`	The total quantity of the digital asset in the customer's portfolio. The value of this field is the sum of the `available` and `reserved` fields' values.
`available`	The quantity of the digital asset that is available for trading.
`reserved`	The quantity of the digital asset that is not available for trading.
`lastUpdated`	The time at which the balance of the digital asset was fetched.

For the full Balance object schema, see the Retrieve current balance operation reference.

Get the balances of all assets in the portfolio

In this tutorial, you request the balances of all digital assets in a customer's Liquidity Hub account portfolio.

Construct the request

The GET /balances operation doesn't accept any parameters. Send a GET request to get the balances of all digital assets in a customer's portfolio.

curl

Examine the response

The code sample below shows the success response received from the /balances endpoint. The balanceList field in the response contains an array of Balance objects. Each object represents the balance of one digital asset in the customer's portfolio. In this example, the array objects represent balances of ETH and BTC digital assets.

Copy

Copied!

{
  "balanceList": [
    {
      "asset": "ETH",
      "total": "13.06919226",
      "available": "13.00000000",
      "reserved": "0.06919226",
      "lastUpdated": "2021-01-01T01:00:30.000Z",
      "endUserGuid": "669ce446-22d0-11ec-9621-0242ac130002"
    },
    {
      "asset": "BTC",
      "total": "8.02564856",
      "available": "8.00000000",
      "reserved": "0.02564856",
      "lastUpdated": "2021-01-01T01:00:30.000Z",
      "endUserGuid": "669ce446-22d0-11ec-9621-0242ac130002"
    }
  ]
}

For more information about key fields in the Balance object, see the previous section. For the full Balance object schema, see the Retrieve current balance 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.

Here are some recommendations for error handling:

Error code	Name	Possible cause and 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 wrong. 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.

Reconcile asset balances

You can use the information returned by the /balances/{asset} and /balances endpoints to reconcile the asset and portfolio balances in Liquidity Hub with your own records.

To reconcile asset balances:

Get the balance of a specific asset or get the balance of all assets in the portfolio.
Parse the response from the endpoint to get the total, available, and reserved balance values associated with an asset.
Compare the balance information with your records.

If you are unable to reconcile a balance, submit a ticket in our support portal for assistance.

Next steps

To learn how to reconcile trading activity with your records, see the Reconcile trading activity tutorial.