# List wallets > The wallets.list operation: GET /api/v1/wallets in the REST API and the wallets_list tool in the MCP server. Lists the brand's wallets in the mode of the request, newest first, with their balances (without the upcoming expiries: get a wallet for those). - `customerId`: one customer's wallets (one per currency); - `currency`, `status`: only wallets in this currency or with this status. Paginate with `limit` (1–100, default 10) and `starting_after` (the `next_cursor` of the previous page). ## At a glance - **REST:** `GET /api/v1/wallets` - **MCP tool:** `wallets_list` - **Operation ID:** `wallets.list` - **Scope:** Brand - **Permission:** `wallets: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:** API key with the `wallets:read` scope - **Since:** M6 ## Request ### Query parameters | Field | Type | Required | Description | | ---------------- | ----------------------------------- | -------- | -------------------------------------------------- | | `limit` | integer (1 to 100) | No | | | `starting_after` | `wal_…` ID | No | | | `customerId` | `cus_…` ID | No | Only this customer's wallets (spec: `?customer=`). | | `currency` | string | No | Only wallets in this currency. | | `status` | one of `active`, `frozen`, `closed` | No | Only wallets with this status. | ## 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` | `wal_…` ID | | | `data[].object` | `"wallet"` | | | `data[].brandId` | `brd_…` ID | | | `data[].livemode` | boolean | | | `data[].customerId` | `cus_…` ID | | | `data[].currency` | string | | | `data[].status` | one of `active`, `frozen`, `closed` | `active`, `frozen` (no new reservations or leases) or `closed` (retired; reopened by a purchase). | | `data[].statusReason` | string or null | Why the wallet is frozen or closed. | | `data[].statusChangedAt` | date-time or null | | | `data[].available` | money | Spendable purchased, subscription and adjustment credits (not reserved). Expired credits stay here until the hourly expiry job takes them out. | | `data[].promo` | money | Spendable promo credits (spent first; never refundable). | | `data[].reserved` | money | Held by open reservations and leases. | | `data[].balance` | money | All unspent credits: `available + promo + reserved`. | | `data[].lowBalanceThreshold` | money or null | | | `data[].lowBalance` | boolean | The balance is below `lowBalanceThreshold`. | | `data[].autoReload` | object or null | | | `data[].createdAt` | date-time | | | `data[].updatedAt` | date-time | | | `has_more` | boolean | | | `next_cursor` | string or null | | ## Examples ### A customer's wallets ```http GET /api/v1/wallets?customerId=cus_01m4ty3c2b5qx7mhd9k8w6s0aa Authorization: Bearer or_test_… ``` Response (`200`): ```json { "object": "list", "data": [ { "id": "wal_01m4ty7w2a5qx7mhd9k8w6s0b1", "object": "wallet", "brandId": "brd_01m4tx5nj8emwbyf7y9vcf47x4", "livemode": false, "customerId": "cus_01m4ty3c2b5qx7mhd9k8w6s0aa", "currency": "EUR", "status": "active", "statusReason": null, "statusChangedAt": null, "available": { "amount": "77000000", "currency": "EUR" }, "promo": { "amount": "5000000", "currency": "EUR" }, "reserved": { "amount": "3000000", "currency": "EUR" }, "balance": { "amount": "85000000", "currency": "EUR" }, "lowBalanceThreshold": { "amount": "10000000", "currency": "EUR" }, "lowBalance": false, "autoReload": null, "createdAt": "2026-10-14T09:00:00.000Z", "updatedAt": "2026-10-16T10:15: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 | A filter or pagination value is invalid. | Fix the fields listed in `details.issues` and send the request again. | | [`scope_required`](https://ownrecord.io/docs/reference/errors.md#scope_required) | 400 | The request names no brand (an org or entity key without `Ownrecord-Brand`). | Call the operation with credentials or a target at its level: an organization, a legal entity, a brand or the platform (`details.required_scope`). | | [`permission_denied`](https://ownrecord.io/docs/reference/errors.md#permission_denied) | 403 | You can't read this brand's wallets (`wallets:read`). | Ask an organization owner or admin for a role or scope that allows this action. | | [`livemode_not_allowed`](https://ownrecord.io/docs/reference/errors.md#livemode_not_allowed) | 403 | You have no live-mode access, so you can't use live wallets. | Use test mode, or credentials for the target's mode. Developers need live access granted by an organization owner or admin. | 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), [`resource_not_found`](https://ownrecord.io/docs/reference/errors.md#resource_not_found), [`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).