> ## Documentation Index
> Fetch the complete documentation index at: https://docs.peerpesa.co/llms.txt
> Use this file to discover all available pages before exploring further.

# List orders and their on-chain transactions with pagination

> GET /orders lists your PeerPesa swap, send, buy, withdraw, and deposit orders with amounts, fees, rates, status, and the on-chain transactions behind each one.

An order is one action you take in PeerPesa, such as swapping cUSD to USDT or sending crypto to a wallet. Each order records what you sent, what the recipient received, the fees and exchange rate, and its status. It also lists the individual `transactions` that carried it out: a swap, for example, has one transaction debiting your wallet and one crediting the recipient, each with its own `tx_hash`.

## GET /orders

Returns your orders, newest first. Supports all [pagination and filter parameters](/pagination) plus order-specific filters.

### Pagination

<ParamField query="page" type="integer" default="1">
  Page number to return, starting at `1`.
</ParamField>

<ParamField query="size" default="20" type="integer">
  Orders per page. Maximum is `100`.
</ParamField>

<ParamField query="limit" default="20" type="integer">
  Alias for `size`. If you send both, `size` is used.
</ParamField>

### Search and dates

<ParamField query="search" type="string">
  Matches `order_id`, `sender_address`, `recipient_address`, `account_number`, asset symbols, and the `tx_hash` of any transaction in the order. Minimum 2 characters.
</ParamField>

<ParamField query="start_date" type="string">
  Only include orders created on or after this date (`YYYY-MM-DD` or ISO 8601).
</ParamField>

<ParamField query="end_date" type="string">
  Only include orders created on or before this date (`YYYY-MM-DD` or ISO 8601).
</ParamField>

### Filters

<ParamField query="order_type" type="string">
  Filter by order type, for example `swap`, `send`, `buy`, `withdraw`, or `deposit`. Comma-separate to match several.
</ParamField>

<ParamField query="status" type="string">
  Filter by order status, for example `successful`. Comma-separate to match several.
</ParamField>

<ParamField query="asset" type="string">
  Only include orders where `from_asset` or `to_asset` matches, for example `cUSD` or `USDT`.
</ParamField>

<ParamField query="network" type="string">
  Only include orders on this network code, for example `cusd`.
</ParamField>

<ParamField query="fiat_currency" type="string">
  Only include fiat orders in this currency, for example `KES`.
</ParamField>

<ParamField query="recurring_payment" type="string">
  Only include orders created by this [recurring payment](/api-reference/recurring-payments).
</ParamField>

<ParamField query="min_amount" type="number">
  Only include orders with `amount` greater than or equal to this value.
</ParamField>

<ParamField query="max_amount" type="number">
  Only include orders with `amount` less than or equal to this value.
</ParamField>

### Sorting

<ParamField query="sort_by" default="created_at" type="string">
  `created_at`, `updated_at`, or `amount`.
</ParamField>

<ParamField query="sort_order" default="desc" type="string">
  `desc` or `asc`.
</ParamField>

<CodeGroup>
  ```bash cURL theme={null}
  curl -G "https://api.peerpesa.co/v1/orders" \
    -H "Authorization: Bearer $ACCESS_TOKEN" \
    --data-urlencode "order_type=swap" \
    --data-urlencode "status=successful" \
    --data-urlencode "search=cUSD" \
    --data-urlencode "start_date=2026-07-01" \
    --data-urlencode "end_date=2026-07-31" \
    --data-urlencode "page=1" \
    --data-urlencode "size=20"
  ```

  ```javascript JavaScript theme={null}
  const query = new URLSearchParams({
    order_type: "swap",
    status: "successful",
    search: "cUSD",
    start_date: "2026-07-01",
    end_date: "2026-07-31",
    page: 1,
    size: 20,
  });
  const res = await fetch(`https://api.peerpesa.co/v1/orders?${query}`, {
    headers: { Authorization: `Bearer ${accessToken}` },
  });
  const { data: orders, pagination } = await res.json();
  ```
</CodeGroup>

```json Response theme={null}
{
  "data": [
    { "order_id": "22573706304032", "order_type": "swap", "status": "successful" }
  ],
  "pagination": {
    "page": 1,
    "size": 20,
    "total": 1,
    "total_pages": 1
  }
}
```

Each item in `data` is a full order object, including its `transactions` array. See [Order Details](/api-reference/order-details) for the complete object, every field, and how to fetch a single order by `order_id`.

## Errors

| Code | Status | Cause |
| - | - | - |
| `invalid_parameter` | 400 | `size` or `limit` is above `100`, or a filter value is invalid. |
| `invalid_date_range` | 400 | `start_date` is after `end_date`. |
| `unauthorized` | 401 | Token missing or expired. |

See [Error Codes](/errors) for the full list.

<CardGroup cols={2}>
  <Card title="Order Details" icon="receipt" href="/api-reference/order-details">
    Fetch one order and its transaction legs.
  </Card>

  <Card title="Pagination & Filters" icon="filter" href="/pagination">
    Shared paging, search, and date parameters.
  </Card>
</CardGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.