GET /api/wallets/user/:userId — list all wallets for a user

List every wallet belonging to a user. Returns wallet configurations, virtual account details, and API key prefixes. Useful for populating a wallet management dashboard.

Return every wallet associated with a given user, ordered by creation date descending. Each wallet in the response includes its full configuration, virtual account details, and API key prefixes. Use this endpoint to populate a wallet management dashboard or to let users audit which agents have been provisioned on their account.

Endpoint

GET /api/wallets/user/:userId

Authentication

Requires a valid Session JWT in the Authorization header.

Authorization: Bearer <session_jwt>

---

Path Parameters

userId · string · required

The UUID of the user whose wallets you want to list. Must match the userId associated with the current session, or the request will be rejected with 403 Forbidden.

---

Response 200 OK

Returns an array of wallet objects, each with the same shape as a single wallet from GET /api/wallets/:walletId — including nested virtualAccount and apiKeys.

[] · object[]

Array of wallet objects belonging to the user.

Show wallet fields

[].id · string

Unique wallet UUID.

[].name · string

Human-readable wallet label.

[].userId · string

UUID of the owning user.

[].businessId · string | null

The associated business ID, or null if not linked to a business account.

[].balance · integer

Current wallet balance in kobo.

[].spendLimitPerTx · integer

Per-transaction spend cap, in kobo.

[].spendLimitPeriod · integer

Rolling-period cumulative spend cap, in kobo.

[].periodWindowDays · integer

Length of the rolling spend window, in days.

[].expiry · string

ISO 8601 datetime at which the wallet deactivates.

[].useAllowlist · boolean

Whether merchant-allowlist enforcement is active.

[].merchantAllowlist · string[]

Permitted merchant names. Empty array when useAllowlist is false.

[].status · string

Wallet lifecycle status (e.g. "ACTIVE").

[].createdAt · string

ISO 8601 timestamp of wallet creation.

[].updatedAt · string

ISO 8601 timestamp of the most recent update.

[].virtualAccount · object

Virtual bank account linked to this wallet.

Show virtualAccount fields

[].virtualAccount.id · string

Virtual account UUID.

[].virtualAccount.walletId · string

The wallet this virtual account is linked to.

[].virtualAccount.accountNumber · string

10-digit Nigerian bank account number.

[].virtualAccount.accountName · string

Account name as displayed on transfers.

[].virtualAccount.bankName · string

Issuing bank name.

[].virtualAccount.providerRef · string

Provider-assigned reference for this virtual account.

[].virtualAccount.createdAt · string

ISO 8601 timestamp of virtual account creation.

[].apiKeys · object[]

API keys for this wallet. Only the key prefix is returned, never fullKey.

Show apiKey fields

[].apiKeys[].id · string

API key UUID.

[].apiKeys[].keyPrefix · string

The prefix characters of the key, safe to display for identification.

[].apiKeys[].createdAt · string

ISO 8601 timestamp of key issuance.

Example Response

[
  {
    "id": "wlt_f7e6d5c4-b3a2-4190-8fed-cba987654321",
    "name": "Procurement Agent — Q3 2025",
    "userId": "usr_a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "businessId": null,
    "balance": 1250000,
    "spendLimitPerTx": 500000,
    "spendLimitPeriod": 2000000,
    "periodWindowDays": 30,
    "expiry": "2027-01-01T00:00:00.000Z",
    "useAllowlist": true,
    "merchantAllowlist": ["AWS", "Vercel", "Stripe"],
    "status": "ACTIVE",
    "createdAt": "2025-07-15T09:41:02Z",
    "updatedAt": "2025-07-15T09:41:02Z",
    "virtualAccount": {
      "id": "va-uuid",
      "walletId": "wlt_f7e6d5c4-b3a2-4190-8fed-cba987654321",
      "accountNumber": "9876543210",
      "accountName": "Procurement Agent — Q3 2025",
      "bankName": "Providus Bank",
      "providerRef": "mock-ref-abc123",
      "createdAt": "2025-07-15T09:41:02Z"
    },
    "apiKeys": [
      {
        "id": "key_aabbccdd-eeff-0011-2233-445566778899",
        "keyPrefix": "ax_live_9f2a3b",
        "createdAt": "2025-07-15T09:41:02Z"
      }
    ]
  },
  {
    "id": "wlt_c1d2e3f4-a5b6-4789-0cde-f12345678901",
    "name": "Travel Booking Agent",
    "userId": "usr_a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "businessId": null,
    "balance": 3500000,
    "spendLimitPerTx": 1000000,
    "spendLimitPeriod": 10000000,
    "periodWindowDays": 30,
    "expiry": "2027-12-31T23:59:59Z",
    "useAllowlist": false,
    "merchantAllowlist": [],
    "status": "ACTIVE",
    "createdAt": "2025-06-01T14:22:10Z",
    "updatedAt": "2025-06-01T14:22:10Z",
    "virtualAccount": {
      "id": "va-uuid-2",
      "walletId": "wlt_c1d2e3f4-a5b6-4789-0cde-f12345678901",
      "accountNumber": "0987654321",
      "accountName": "Travel Booking Agent",
      "bankName": "Providus Bank",
      "providerRef": "mock-ref-def456",
      "createdAt": "2025-06-01T14:22:10Z"
    },
    "apiKeys": [
      {
        "id": "key_11223344-aabb-ccdd-eeff-001122334455",
        "keyPrefix": "ax_live_7c1e2d",
        "createdAt": "2025-06-01T14:22:10Z"
      }
    ]
  }
]

---

Error Responses

Status	Code	Description
401	UNAUTHORIZED	Missing or invalid Session JWT.
403	FORBIDDEN	The authenticated session does not have access to the requested userId.
404	USER_NOT_FOUND	No user exists with the supplied userId.

{
  "error": {
    "code": "FORBIDDEN",
    "message": "You do not have permission to list wallets for this user."
  }
}