What is the cursor?

The cursor is our implementation of a paging solution. When querying lister endpoints like listing orders or assets there is a concept of page size and cursor. The page size states how many results should be displayed in a single response and the cursor contains the last element in that list based on the query parameters. The remaining field indicates whether there are still results remaining for the query (1: yes, 0: no).

The cursor is a base64 encoded string which has some of the data points of the items in the request. Here is a simple example:

Query will return a list of assets in a page size of 3 in an ascending order by updated_at. It returns 3 items and the following cursor:

eyJpZCI6IjB4NmYzMDRhMjc1YjU4YjZhMmI0NDg3YTRiNmU3OWZlNmQwNGNlNjg2ZGIwMTY5NDRlZGYyODc0NTA1NzhhZTQ0ZiIsIm5hbWUiOm51bGwsInVwZGF0ZWRfYXQiOiIyMDIyLTExLTE1VDE0OjEzOjAyLjU5MTI4N1oifQ

If we decode this from base64:

Encoding and Decoding Base64 Strings in Node.js
Encoding and Decoding Base64 Strings in Python
How to do Base64 Encoding and Decoding in PowerShell?

{
    "id": "0x6f304a275b58b6a2b4487a4b6e79fe6d04ce686db016944edf287450578ae44f",
    "name": null,
    "updated_at": "2022-11-15T14:13:02.591287Z"
}

This data is then used to indicate the starting point for the next API call.

Remaining page returns 1 with no remaining results

If the last item returned by the current page is the final item in the entire set, the API will return remaining: 1. Polling the next page will give empty results.

Code Example

listAllOrdersFromMultipleCollections.ts:

// List OrdersInCollections
import { ImmutableX, Config, OrdersApiListOrdersRequest } from '@imtbl/core-sdk';
//Single return of response from the endpoint
async function listOrdersInCollections(cursor:string, collection:string) {
    
    const config = Config.SANDBOX; 
    const client = new ImmutableX(config);
    let listOrdersInCollectionResponse: any;
    const ordersRequestParam : OrdersApiListOrdersRequest = {
      cursor: cursor,
      pageSize: 20,
      sellTokenAddress: collection,
      status:"filled"
      
    }
    listOrdersInCollectionResponse = await client.listOrders(ordersRequestParam);

    return listOrdersInCollectionResponse;

}
//enumerates throught the cursor of a request endpoint
async function enumerateOrdersCursor(collection:string) {

  let orders:Object[] = [];
  let remaining = 1;
  let throttleCount = 0;
  let cursor = '';
  while(remaining == 1 )
  {
    const response = await listOrdersInCollections(cursor,collection);
    remaining = response.remaining;
    cursor = response.cursor;
    orders = orders.concat(response.result);
    throttleCount++
    if((throttleCount%5)==0)
    {
      const sleep = new Promise(resolve => setTimeout(resolve, 1000));
    }     
  }
  return orders;
}
// 
async function main()  {
  // Multiple collections to enumerate through
  const collections = ['0x07f68c5cda94347bf1c34ce398330aa42c0842b7','0xb40a0dfa154713366e03efb12a325b9b8daecce7']
  let orders:Object[] = [];
  // enumerate through array and get order results for each collection
  for(const collection in collections)
  {
    const element = collections[collection];
    const result = await enumerateOrdersCursor(element);
    orders = orders.concat(result);
  }

  console.log(orders);

}   

main()
.then(() => console.log('listOrdersInCollections call complete'))
.catch(err => {
console.error(err);
process.exit(1);
});

This is a script that interacts with the Immutable X API to retrieve a list of filled orders for specified collections. Let's break down the script step by step:

Import Statements:
- The script begins with import statements that bring in necessary modules from the @imtbl/core-sdk package. These modules provide the tools to interact with the Immutable X API.
listOrdersInCollections Function:
- This asynchronous function retrieves a list of filled orders within a specific collection.
- It takes two parameters: cursor (a string indicating a cursor for pagination) and collection (the address of the collection for which to fetch orders).
- It creates a configuration for the Immutable X API, initializes a client, and constructs a request object for listing orders within the specified collection.
- It calls the listOrders method of the client and returns the response containing the list of orders.
enumerateOrdersCursor Function:
- This asynchronous function retrieves a paginated list of orders for a given collection by repeatedly calling the listOrdersInCollections function.
- It uses a while loop to keep fetching orders until there are no remaining orders to fetch.
- The response from each API call is used to update the remaining count, cursor, and the orders array.
- There's a throttle mechanism that pauses for 1 second after every 5 API calls to avoid going over the public API throttle limit.
main Function:
- This is the main entry point of the script.
- It defines an array of collection addresses to process.
- It iterates through each collection, calling the enumerateOrdersCursor function to retrieve orders for each collection, and concatenates the results into the orders array.
- Finally, it logs the complete list of orders.
Executing main Function:
- The script then calls the main function.
- After the main function is executed, it logs a message indicating that the process is complete.
Error Handling:
- If there's an error during the execution, it is caught, logged, and the script exits with an exit code of 1.

In summary, this script fetches a list of filled orders from the Immutable X API for specified collections, handling pagination and rate limiting to ensure a smooth interaction with the API. The retrieved orders are then logged to the console.