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.
/api/v1/portal/me/wallets/{walletId}/transactionsLists 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) andstarting_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
GET /api/v1/portal/me/wallets/wal_01m4tx5nj8emwbyf7y9vcf48c7/transactions
Authorization: Bearer or_test_…
Response (200):
{
"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 | 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 | 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 | 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 | 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: api_version_unsupported, authentication_required, api_key_invalid, scope_required, dry_run_not_supported, rate_limited, internal_error.