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

# List Wallets

> Retrieve every wallet provisioned for your company, with current balances broken down into pay-in and pay-out sub-balances.

## Overview

`GET /wallets` returns every wallet provisioned under your company. Each entry includes the current `payin_balance` and `payout_balance`, plus configured phone numbers and operators.

For a slimmer balances-only view, see [`GET /payment/balance`](/api-reference/endpoint/get-payment-balance).

## When to use it

* Render a wallets overview in your dashboard.
* Look up a wallet's `id` for use in other endpoints.
* Inspect configured operators per wallet.

## Prerequisites

* Authenticated as a company user.

## Request

### Headers

| Name            | Required | Description             |
| --------------- | -------- | ----------------------- |
| `Authorization` | Yes      | `Bearer <access_token>` |

No query parameters or body.

## Response

### 200 — Success

```json theme={null}
{
  "success": true,
  "statusCode": 200,
  "message": "Data retrieved successfully",
  "data": [
    {
      "id": "w1a2b3c4-d5e6-7890-abcd-ef1234567890",
      "company_id": "c1a2b3c4-d5e6-7890-abcd-ef1234567890",
      "currency": "XAF",
      "country": "Cameroon",
      "country_iso_code": "CM",
      "country_phone_code": "+237",
      "balance": 175000,
      "payin_balance": 125000,
      "payout_balance": 50000,
      "payin_amount": 200000,
      "payout_amount": 75000,
      "amount_to_recover": 0,
      "is_active": true,
      "created_at": "2026-04-01T08:00:00.000Z",
      "updated_at": "2026-05-09T10:15:00.000Z",
      "phoneNumbers": [
        { "id": "...", "phone_number": "237670000000", "operator": "mtn", "is_default": true }
      ],
      "operators": [
        { "operator_code": "mtn", "payin_active": true, "payout_active": true },
        { "operator_code": "orange", "payin_active": true, "payout_active": false }
      ]
    }
  ]
}
```

### Field reference

| Field               | Type    | Description                                                                                   |
| ------------------- | ------- | --------------------------------------------------------------------------------------------- |
| `id`                | string  | Wallet ID (UUID).                                                                             |
| `currency`          | string  | ISO 4217.                                                                                     |
| `country_iso_code`  | string  | ISO 3166-1 alpha-2.                                                                           |
| `payin_balance`     | number  | Funds collected from end users, currently in this wallet.                                     |
| `payout_balance`    | number  | Funds available to disburse via `POST /payment/payout`.                                       |
| `balance`           | number  | Total balance (typically `payin_balance + payout_balance`).                                   |
| `payin_amount`      | number  | Lifetime pay-in volume.                                                                       |
| `payout_amount`     | number  | Lifetime pay-out volume.                                                                      |
| `amount_to_recover` | number  | Outstanding debt against this wallet (see [Glossary → Debt](/getting-started/glossary#debt)). |
| `is_active`         | boolean | `false` when an admin has disabled the wallet.                                                |
| `phoneNumbers`      | array   | Mobile-money phone numbers configured against this wallet.                                    |
| `operators`         | array   | Operators enabled for pay-in / pay-out on this wallet.                                        |

### Error responses

| Status | Trigger                          |
| ------ | -------------------------------- |
| `401`  | Missing or expired Bearer token. |

## Code examples

```bash cURL theme={null}
curl https://api.cartevo.co/api/v1/wallets \
  -H "Authorization: Bearer $TOKEN"
```

```js Node.js (axios) theme={null}
const { data } = await axios.get("https://api.cartevo.co/api/v1/wallets", {
  headers: { Authorization: `Bearer ${token}` },
});
const usdWallet = data.data.find((w) => w.currency === "USD");
```

## Related

* [`GET /wallets/{id}`](/api-reference/endpoint/get-wallet-by-id) — single wallet detail.
* [`GET /payment/balance`](/api-reference/endpoint/get-payment-balance) — slim balances view.
* [`POST /wallets`](/api-reference/endpoint/post-wallets) — create a new wallet.


## OpenAPI

````yaml GET /wallets
openapi: 3.1.0
info:
  title: Cartevo API
  description: Essential endpoints for wallets, transactions, customers and conversion.
  version: 1.0.0
servers:
  - url: https://api.cartevo.co/api/v1
security:
  - bearerAuth: []
paths:
  /wallets:
    get:
      summary: List wallets
      description: Retrieves a list of all wallets for the authenticated company.
      responses:
        '200':
          description: A list of wallets associated with the company.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListWalletsResponse'
components:
  schemas:
    ListWalletsResponse:
      allOf:
        - $ref: '#/components/schemas/StandardResponse'
        - type: object
          properties:
            data:
              type: array
              items:
                $ref: '#/components/schemas/Wallet'
    StandardResponse:
      type: object
      properties:
        success:
          type: boolean
          example: true
        statusCode:
          type: integer
          example: 200
        message:
          type: string
          example: Data retrieved successfully
    Wallet:
      type: object
      properties:
        id:
          type: string
          format: uuid
          example: 422541f3-80e2-41e0-b7a2-24017586b374
        balance:
          type: string
          example: '0.24'
        payin_balance:
          type: string
          example: '306'
        payout_balance:
          type: string
          example: '1646'
        payin_amount:
          type: string
          example: '982.6'
        payout_amount:
          type: string
          example: '1994'
        amount_to_recover:
          type: string
          example: '0'
        is_active:
          type: boolean
          example: true
        currency:
          type: string
          example: XAF
        country:
          type: string
          example: Cameroon
        country_iso_code:
          type: string
          example: CM
        company_id:
          type: string
          format: uuid
          example: eca5e982-00b5-4aa2-b709-7d5cd673e95c
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
        country_phone_code:
          type: string
          example: '237'
        phoneNumbers:
          type: array
          items:
            $ref: '#/components/schemas/PhoneNumber'
        operators:
          type: array
          items:
            $ref: '#/components/schemas/Operator'
    PhoneNumber:
      type: object
      properties:
        id:
          type: string
          format: uuid
          example: 32e525ac-a4a3-47fa-896e-4ef89f64d2d0
        wallet_id:
          type: string
          format: uuid
          example: 422541f3-80e2-41e0-b7a2-24017586b374
        country_iso_code:
          type: string
          example: CM
        country_phone_code:
          type: string
          example: '+237'
        currency:
          type: string
          example: XAF
        phone_number:
          type: string
          example: '650695112'
        operator:
          type: string
          example: MTN
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
    Operator:
      type: object
      properties:
        id:
          type: string
          format: uuid
          example: f079c4db-4897-4ae7-9371-87950ad2429c
        country_iso_code:
          type: string
          example: CM
        country_phone_code:
          type: string
          example: '237'
        currency:
          type: string
          example: XAF
        operator_code:
          type: string
          example: mtn
        operator_name:
          type: string
          example: MTN Money
        otp_required:
          type: boolean
          example: false
        ussd_code:
          type: string
          nullable: true
          example: '*126#'
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer

````