# List your wallet's history

> The portal.wallets.transactions.list operation: GET /api/v1/portal/me/wallets/{walletId}/transactions in the REST API and the portal_wallets_transactions_list tool in the MCP server.

Lists what moved one of the signed-in customer's wallets, newest first, from the ledger: top-ups, included and
promotional credits, usage, holds and their release, expiries and refunds. Each entry has its category and the
signed change of the balance and of each part. Operators' notes and internal references aren't shown.
Paginate with `limit` and `starting_after`. Customer portal only (`portal:read`).

## At a glance

- **REST:** `GET /api/v1/portal/me/wallets/{walletId}/transactions`
- **MCP tool:** `portal_wallets_transactions_list`
- **Operation ID:** `portal.wallets.transactions.list`
- **Scope:** Brand
- **Permission:** `portal:read`
- **Risk tier:** `read`
- **Dry run:** Not supported
- **Idempotency:** Not needed (read only)
- **Modes:** Test and live
- **Pagination:** `limit` (at most 100) and `starting_after`
- **Authentication:** A customer signed in to the customer portal (API keys can't call it)
- **Since:** M9

## Request

### Path parameters

| Field      | Type       | Description                    |
| ---------- | ---------- | ------------------------------ |
| `walletId` | `wal_…` ID | One of your wallets (`wal_…`). |

### Query parameters

| Field            | Type               | Required | Description                             |
| ---------------- | ------------------ | -------- | --------------------------------------- |
| `limit`          | integer (1 to 100) | No       | Page size, 1 to 100 (default 20).       |
| `starting_after` | string             | No       | The `next_cursor` of the previous page. |

## Response

`200 OK` with a JSON object, a page of the list (newest first):

| Field                | Type                                                                                            | Description                                                                                                                                           |
| -------------------- | ----------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
| `object`             | `"list"`                                                                                        |                                                                                                                                                       |
| `data`               | array of object                                                                                 |                                                                                                                                                       |
| `data[].id`          | `txn_…` ID                                                                                      |                                                                                                                                                       |
| `data[].object`      | `"portal_wallet_entry"`                                                                         |                                                                                                                                                       |
| `data[].walletId`    | `wal_…` ID                                                                                      |                                                                                                                                                       |
| `data[].type`        | one of `top_up`, `credits_added`, `used`, `held`, `released`, `expired`, `refunded`, `adjusted` | `top_up`, `credits_added` (included or promotional credits), `used`, `held` (for usage in progress), `released`, `expired`, `refunded` or `adjusted`. |
| `data[].balance`     | money                                                                                           | The signed change of your balance (holds and releases don't change it).                                                                               |
| `data[].available`   | money                                                                                           |                                                                                                                                                       |
| `data[].promo`       | money                                                                                           |                                                                                                                                                       |
| `data[].reserved`    | money                                                                                           |                                                                                                                                                       |
| `data[].effectiveAt` | date-time                                                                                       |                                                                                                                                                       |
| `has_more`           | boolean                                                                                         |                                                                                                                                                       |
| `next_cursor`        | string or null                                                                                  |                                                                                                                                                       |

## Examples

### A top-up

```http
GET /api/v1/portal/me/wallets/wal_01m4tx5nj8emwbyf7y9vcf48c7/transactions
Authorization: Bearer or_test_…
```

Response (`200`):

```json
{
  "object": "list",
  "data": [
    {
      "id": "txn_01m4tx5nj8emwbyf7y9vcf48c8",
      "object": "portal_wallet_entry",
      "walletId": "wal_01m4tx5nj8emwbyf7y9vcf48c7",
      "type": "top_up",
      "balance": {
        "amount": "25000000",
        "currency": "EUR"
      },
      "available": {
        "amount": "25000000",
        "currency": "EUR"
      },
      "promo": {
        "amount": "0",
        "currency": "EUR"
      },
      "reserved": {
        "amount": "0",
        "currency": "EUR"
      },
      "effectiveAt": "2026-11-05T09:30:00.000Z"
    }
  ],
  "has_more": false,
  "next_cursor": null
}
```

## Errors

| Code                                                                                         | HTTP status | When                                                                                                                              | What to do                                                                                                                  |
| -------------------------------------------------------------------------------------------- | ----------- | --------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------- |
| [`validation_failed`](https://ownrecord.io/docs/reference/errors.md#validation_failed)       | 400         | The wallet's ID or a pagination value is malformed.                                                                               | Fix the fields listed in `details.issues` and send the request again.                                                       |
| [`resource_not_found`](https://ownrecord.io/docs/reference/errors.md#resource_not_found)     | 404         | You have no such wallet (another customer's reads the same).                                                                      | Check the ID and that your credentials are scoped to the right organization, entity, brand and mode.                        |
| [`livemode_not_allowed`](https://ownrecord.io/docs/reference/errors.md#livemode_not_allowed) | 403         | The portal session is in the other mode than the request.                                                                         | Use test mode, or credentials for the target's mode. Developers need live access granted by an organization owner or admin. |
| [`permission_denied`](https://ownrecord.io/docs/reference/errors.md#permission_denied)       | 403         | The caller isn't a customer signed in to this brand's portal (operators and API keys use the subscription and wallet operations). | Ask an organization owner or admin for a role or scope that allows this action.                                             |

It can also return these [common errors](https://ownrecord.io/docs/reference.md#common-errors): [`api_version_unsupported`](https://ownrecord.io/docs/reference/errors.md#api_version_unsupported), [`authentication_required`](https://ownrecord.io/docs/reference/errors.md#authentication_required), [`api_key_invalid`](https://ownrecord.io/docs/reference/errors.md#api_key_invalid), [`scope_required`](https://ownrecord.io/docs/reference/errors.md#scope_required), [`dry_run_not_supported`](https://ownrecord.io/docs/reference/errors.md#dry_run_not_supported), [`rate_limited`](https://ownrecord.io/docs/reference/errors.md#rate_limited), [`internal_error`](https://ownrecord.io/docs/reference/errors.md#internal_error).