Reconcile trading activity

This tutorial shows you how to use the Liquidity Hub API to reconcile trading activity. You can call the GET /trades operation to get a snapshot of trading activities during a specific time period and reconcile the details with your own records.

In this tutorial you will learn how to:

Get the list of trades for your account.
Reconcile the information returned by the GET /trades operation with your own records.

Prerequisites

The /trades 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.

Step 1: Get the list of trades

To get the list of all trades that were completed succesfully during a specific time period, call the GET /trades operation.

Construct the request

The GET /trades operation accepts optional query parameters to filter the trade activity returned in the response. In this example, we fetch the list of all trades completed during a specific period of time. To do this, specify the following query parameters in the request:

Query parameter	Description	Value
`startTime`	Get the list of successful trades that occurred at or after this time.	`2023-01-01T01:00:00.000Z`
`endTime`	Get the list of successful trades that occurred at or before this time.	`2023-01-01T02:00:00.000Z`
`pageSize`	The number of `Trade` objects to return per response.	`2`
`pageNumber`	The sequence number of the page of results to retrieve. Start at page `0` and increment the value of this parameter in subsequent requests.	`0`

Request sample

Use the following code sample to request the list of successful trades completed during a specific period of time:

Copy

Copied!

curl -i -X GET \
  https://docs.ripple.com/api/v0/trades?startTime=2023-01-01T01%3A00%3A00.000Z&endTime=2023-01-01T02%3A00%3A00.000Z&pageSize=2&pageNumber=0 \
  -H 'Authorization: Bearer <YOUR_TOKEN_HERE>'

Examine the response

The following code sample shows the success response received from the /trades endpoint. The response contains an array of Trade objects where each object represents a successfully completed trade. This example returns two Trade objects in the array because we requested a pageSize of 2.

Copy

Copied!

{
  "tradesList": [
    {
      "tradeId": "065e2c46-be89-4fe2-9d16-ce9afeca50b7",
      "price": "51345.76",
      "baseAsset": "BTC",
      "quoteAsset": "USD",
      "baseAssetQty": "1.00000000",
      "quoteAssetQty": "51345.76",
      "side": "BUY",
      "endUserGuid": "669ce446-22d0-11ec-9621-0242ac130002",
      "timestamp": "2023-01-01T01:05:30.000Z",
      "quoteId": "fd5dbe64-a96e-4e1c-9843-75cd6b0cdb60"
    },
    {
      "tradeId": "039e2e28-b29d-8274-9smb-z61afeca50b7",
      "price": "50321.98",
      "baseAsset": "BTC",
      "quoteAsset": "USD",
      "baseAssetQty": "2.00000000",
      "quoteAssetQty": "100643.96",
      "side": "BUY",
      "endUserGuid": "669ce446-22d0-11ec-9621-0242ac130002",
      "timestamp": "2023-01-01T01:30:30.000Z",
      "quoteId": "bs7db9sg-y45d-0e76-6376-33dd6b1cef67"
    }
  ],
  "totalPages": 10,
  "first": true,
  "last": false,
  "totalElements": 20
}

Let's take a closer look at the key fields in the Trade object that are useful in reconciling trading activity:

Field	Description
`price`	The price at which the trade was executed.
`baseAssetQty`	The quantity of `baseAsset` that was bought or sold in the trade.
`quoteAssetQty`	The quantity of `quoteAsset` that was bought or sold in the trade.
`side`	Indicates whether you bought or sold the `baseAsset` in the trade.
`timeStamp`	The time at which the trade was completed.

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

Paginate to get all matching trades

Check the value of the last field in the response to see if you have retrieved all trade records that match the query parameters specified in the request.In this example, the last field is set to false. This means there are more trades that were completed between the startTime and endTime that you need to fetch. To fetch the remaining trades, increment the value of the pageNumber field in the request and call the GET /trades operation again. Repeat the call until the value of the last field in the response is true.

For more information, see Pagination.

Step 2: Reconcile the list with your records

To reconcile the trade data you received from the Liquidity Hub API with your records:

Take a snapshot of your trading activity records starting at the startTime and ending at the endTime you specified as query parameters in the GET /trades call.
Parse the response(s) you received from the /trades endpoint to get the information associated with each trade.
Compare the information (for example, trade price, asset quantity, whether an asset was bought or sold) with your records.

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

Next step: Reconcile asset balances

See the Get asset and portfolio balances tutorial to retrieve the balance of the assets in your portfolio and reconcile them with your records.