Pagination

Consistent page-based pagination used across all list endpoints.

Overview

List endpoints use page-based pagination with two query parameters:

• limit — number of items per page (default 50, min 1, max 100)
• page — 1-based page index (default 1)

Results are wrapped in a standard envelope with a data.items[] array and a data.meta object that reports the pagination state.

Request

Pass limit and page as query parameters on any list endpoint (e.g., chains, loans, withdrawals, corridors, utilizations).

GET /api/v2/liquidity/management/loans?limit=50&page=2
authorization: Bearer <token>
x-api-key: <key>

Common query parameters

Name	In	Type	Default	Min	Max	Notes
limit	query	integer	50	1	100	Items per page
page	query	integer	1	1	—	1-based page number

Some endpoints also accept additional filters (e.g., status, chainId, loan_id, corridor_id). Filters combine with pagination.

Response Shape

All list responses follow the same structure:

{
  "items": [ /* array of resources */ ],
  "meta": {
    "limit": 50,
    "page": 2,
    "total": 1234
  }
}

meta fields

• limit — the page size used for this response.
• page — the current 1-based page number.
• total — total number of items that match the query (across all pages).

You can compute total pages as:
totalPages = ceil(total / limit).

Example

GET /api/v2/liquidity/corridors?status=ACTIVE&limit=25&page=3

{
  "items": [
    {
      "id": "corridor_ngn",
      "name": "Nigeria",
      "currency": "NGN",
      "status": "ACTIVE",
      "min_amount": 1000,
      "max_amount": 1000000,
      "created_at": "2025-08-02",
      "updated_at": "2025-08-02"
    }
    // ...
  ],
  "meta": {
    "limit": 25,
    "page": 3,
    "total": 240
  }
}

Best Practices

• Use stable sorting: if the endpoint supports sorting, keep it consistent between requests to avoid duplicates or gaps when data changes.
• Paginate deterministically: when filtering by mutable fields (like status), expect total and page counts to change over time.
• Handle bounds: if page is beyond the last page (page > ceil(total/limit)), you may receive an empty items array.
• Validate inputs: invalid limit/page values return a validation error (400 or 422) with a structured error body.
• Backoff & retry: if you hit rate limits (429), retry with exponential backoff before continuing pagination.