Paginate, search, and filter PeerPesa list endpoints

Every PeerPesa list endpoint, including orders and transaction histories, shares the same query parameters for paging, searching, date filtering, and sorting. Combine them freely: for example, page 2 of successful swaps from July 2026 that mention a wallet address. Each endpoint page also lists the extra filters specific to it.

Common query parameters

Pagination

integer

default:"1"

Page number to return, starting at 1. Requesting a page beyond total_pages returns an empty data array.

integer

default:"20"

Number of items per page. Maximum is 100. Larger values return invalid_parameter.

integer

default:"20"

Alias for size, accepted for compatibility. If you send both, size is used.

Search

string

Free-text search, case-insensitive. Matches IDs and reference numbers (such as order_id or transaction_id), wallet addresses, tx_hash, asset symbols, account numbers, and names, depending on the endpoint. Minimum 2 characters.

Date range

string

Only include items created on or after this date. Accepts YYYY-MM-DD (start of day, UTC) or a full ISO 8601 timestamp.

string

Only include items created on or before this date. Accepts YYYY-MM-DD (end of day, UTC) or a full ISO 8601 timestamp. Must be on or after start_date.

Sorting

string

default:"created_at"

Field to sort by: created_at, updated_at, or amount (where the list has amounts).

string

default:"desc"

desc for newest or largest first, asc for oldest or smallest first.

Status

string

Filter by status. Accepts one value or a comma-separated list, for example status=successful,pending. Valid values depend on the endpoint.

Response format

Response

{
  "data": [
    { "order_id": "22573706304032", "order_type": "swap", "status": "successful" }
  ],
  "pagination": {
    "page": 2,
    "size": 20,
    "total": 134,
    "total_pages": 7
  }
}

object[]

Items on the current page that match your filters.

object

Show properties

integer

Current page number.

integer

Items per page used for this response.

integer

Total number of items matching your filters, across all pages.

integer

Total number of pages. 0 when there are no results.

Examples

curl -G "https://api.peerpesa.co/v1/orders" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  --data-urlencode "search=0x15cb5Ab9" \
  --data-urlencode "start_date=2026-07-01" \
  --data-urlencode "end_date=2026-07-31" \
  --data-urlencode "status=successful" \
  --data-urlencode "page=1" \
  --data-urlencode "size=20"

curl "https://api.peerpesa.co/v1/orders?sort_by=amount&sort_order=desc&size=10" \
  -H "Authorization: Bearer $ACCESS_TOKEN"

async function fetchAll(path, params, accessToken) {
  const items = [];
  let page = 1;
  let totalPages = 1;

  do {
    const query = new URLSearchParams({ ...params, page, size: 100 });
    const res = await fetch(`https://api.peerpesa.co/v1${path}?${query}`, {
      headers: { Authorization: `Bearer ${accessToken}` },
    });
    const { data, pagination } = await res.json();
    items.push(...data);
    totalPages = pagination.total_pages;
    page += 1;
  } while (page <= totalPages);

  return items;
}

const julySwaps = await fetchAll(
  "/orders",
  { order_type: "swap", start_date: "2026-07-01", end_date: "2026-07-31" },
  accessToken
);

New items can arrive while you page through results, which may shift items between pages. For reconciliation, always set a fixed end_date so the result set does not change while you read it.

Errors

Code	Status	Cause
`invalid_parameter`	400	`size` or `limit` above `100`, `page` below `1`, `search` shorter than 2 characters, an unknown `sort_by` field, or a malformed date. The `param` field names the parameter.
`invalid_date_range`	400	`end_date` is before `start_date`.

Endpoints that support these parameters

Endpoint	Lists	Extra filters
`GET /orders`	Orders with their on-chain transactions	`order_type`, `asset`, `network`, `fiat_currency`, `recurring_payment`
`GET /recurring-payments`	Recurring payment schedules	`type`
`GET /recurring-payments/{id}/transactions`	Transactions created by one schedule	None
`GET /fees`	Fee products	`product`, `network`, `asset`, `fiat_currency`, `payment_method`
`GET /beneficiaries`	Saved beneficiaries	`type`, `country`, `fiat_currency`, `network`
`GET /wallets`	Deposit wallets	`network`
`GET /wallets/{id}/deposits`	Deposits received by a wallet	None
`GET /wallets/{id}/lightning`	Lightning addresses and invoices	None
`GET /webhooks/{id}/deliveries`	Webhook delivery attempts	None

Get Started

Reference

Paginate, search, and filter PeerPesa list endpoints

Common query parameters

Search

Date range

Sorting

Status

Response format

Examples

Errors

Endpoints that support these parameters

​Common query parameters

​Pagination

​Search

​Date range

​Sorting

​Status

​Response format

​Examples

​Errors

​Endpoints that support these parameters

Common query parameters

Pagination

Search

Date range

Sorting

Status

Response format

Examples

Errors

Endpoints that support these parameters