Pagination

In this guide, we will learn how to work with cursor-based pagination when querying the Moon Banking API. All list endpoints (i.e. endpoints that return an array of objects) use cursor-based pagination for optimal performance and scalability. By default, responses limit results to 10 items, but you can request up to 100 items per page using the limit parameter.

Cursor-Based Pagination

Moon Banking API uses cursor-based pagination (also known as cursor_id pagination) which is more robust and performant than traditional offset-based pagination, especially for Moon Banking's large datasets. This approach uses the id field of items as cursors to navigate through pages.

Key Benefits

Performance: Consistent query performance regardless of page depth
Real-time Consistency: No duplicate or missing items when data changes
Scalability: Efficient for Moon Banking's large datasets

Parameters

Name: starting_after
Type: string
Description: Cursor for forward pagination. Use the id of the last item from the current page to get the next page.

Name: ending_before
Type: string
Description: Cursor for backward pagination. Use the id of the first item from the current page to get the previous page.

Name: limit
Type: integer
Description: Number of items to return. Minimum: 1, Maximum: 100, Default: 10.

Response Structure

All paginated responses follow this structure:

{
  "success": true,
  "data": [...], // Array of items, each with an "id" field
  "pagination": {
    "hasMore": true,
    "limit": 10,
    "nextCursor": "item-id-for-next-page",
    "previousCursor": "item-id-for-previous-page",
    "meta": {
      "total": 100
    }
  },
  "message": "Items retrieved successfully",
  "timestamp": "2025-01-11T10:30:00.000Z",
  "version": "2025-07-11"
}

Pagination Object Schema

Name: hasMore
Type: boolean
Description: Whether there are more items available.

Name: limit
Type: integer
Description: Number of items per page.

Name: nextCursor
Type: string
Description: Cursor for the next page. Use this as the starting_after parameter for the next request.

Name: previousCursor
Type: string
Description: Cursor for the previous page. Use this as the ending_before parameter for the previous request.

Name: meta
Type: object
Description: For some paginated endpoints, you can include the meta object in the response by including a meta value in the include parameter. For example, the GET /banks endpoint supports the meta parameter.

Example: Fetching Countries

In this example, we request countries starting after the country with id 454hfjsjuusbf. The response shows we have more data available (hasMore: true) and provides the nextCursor for fetching the next page.

Fetch first page

curl -G https://api.moonbanking.com/v1/countries \
  -H "Authorization: Bearer {token}" \
  -d limit=3

First page response

{
  "success": true,
  "data": [
    {
      "id": "454hfjsjuusbf",
      "name": "United States",
      "code": "US"
    },
    {
      "id": "6a78tArVou3i3pf",
      "name": "Canada",
      "code": "CA"
    },
    {
      "id": "7ZK2KIp9gzaSOh8",
      "name": "Australia",
      "code": "AU"
    }
  ],
  "pagination": {
    "hasMore": true,
    "limit": 3,
    "nextCursor": "7ZK2KIp9gzaSOh8",
    "previousCursor": null
  }
}

To fetch the next page, use the nextCursor value from the previous response as the starting_after parameter.

Fetch next page

curl -G https://api.moonbanking.com/v1/countries \
  -H "Authorization: Bearer {token}" \
  -d starting_after="7ZK2KIp9gzaSOh8" \
  -d limit=3

Next page response

{
  "success": true,
  "data": [
    {
      "id": "vlmurWWl3k9gNqh",
      "name": "Germany",
      "code": "DE"
    },
    {
      "id": "HydRnzrfu3eY2CG",
      "name": "France",
      "code": "FR"
    }
  ],
  "pagination": {
    "hasMore": false,
    "limit": 3,
    "nextCursor": null,
    "previousCursor": "vlmurWWl3k9gNqh"
  }
}

Best Practices

Always use cursors: Never try to calculate offsets manually
Handle edge cases: Check hasMore before requesting next pages
Store cursors: Keep track of nextCursor and previousCursor for navigation
Limit appropriately: Use reasonable page sizes (10-50 items) for better performance