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

# Check Wallet Balance

The Wallet Balance API allows clients to retrieve their current LumiID wallet balance and associated account information programmatically.

This endpoint is useful for monitoring available funds, implementing automated wallet monitoring, and checking account balances before initiating identity verification requests.GET

```json theme={null}
GET https://api.lumiid.com/v1/wallet/balance/
```

## 1. Authentication

The endpoint requires your LumiID API key.

Include your API key in the `Authorization` header using the Bearer authentication scheme.

```javascript theme={null}
Authorization: Bearer YOUR_LUMIID_API_KEY
Accept: application/json
```

## 2. Request parameters

No query parameters or request body are required.

| Parameter | Type | Required | Description |
| :- | :- | :- | :- |
| None | — | — | Authentication is handled through the API key. |

## 3. Example request

cURL

```json theme={null}
curl -X GET \
  "https://api.lumiid.com/v1/wallet/balance/" \
  -H "Authorization: Bearer YOUR_LUMIID_API_KEY" \
  -H "Accept: application/json"
```

## 4. Successful response

200 OK

```json theme={null}
{
  "status": "success",
  "balance": "3630.00",
  "client": {
    "name": "Sample Company LTD"
  }
}
```

## 5. Response fields

| Field | Type | Description |
| :- | :- | :- |
| `status` | string | Indicates whether the request was successful. |
| `balance` | string | Current wallet balance, represented as a decimal string. |
| `client` | object | Contains the authenticated client's information. |
| `client.name` | string | Registered organization name associated with the API key. |

Note: The balance is returned as a string to preserve decimal precision. Parse it using a decimal-safe numeric type when performing financial calculations.

## 6. Error responses

### 404 — Wallet not found

Returned when the authenticated organization does not have an associated wallet.

```json theme={null}
{
  "error": "Wallet not found"
}
```

### 401 — Unauthorized

Returned when the API key is missing or invalid, assuming the authentication class returns this status.

```json theme={null}
{
  "error": "Invalid or missing API key."
}
```

## 7. Integration examples

### React.js

For production applications, call this endpoint through your backend to protect your API key.

```javascript theme={null}
import { useState } from "react";

export default function WalletBalance() {
  const [wallet, setWallet] = useState(null);
  const [loading, setLoading] = useState(false);
  const [error, setError] = useState("");

  const fetchBalance = async () => {
    setLoading(true);
    setError("");

    try {
      const response = await fetch("/api/wallet/balance/", {
        headers: {
          Accept: "application/json"
        },
        credentials: "include"
      });

      const data = await response.json();

      if (!response.ok) {
        throw new Error(data.error || "Unable to retrieve balance");
      }

      setWallet(data);
    } catch (err) {
      setError(err.message);
    } finally {
      setLoading(false);
    }
  };

  return (
    <div>
      <button onClick={fetchBalance} disabled={loading}>
        {loading ? "Loading..." : "Check Wallet Balance"}
      </button>

      {error && <p>{error}</p>}

      {wallet && (
        <div>
          <h3>{wallet.client.name}</h3>
          <h2>₦{wallet.balance}</h2>
          <p>Status: {wallet.status}</p>
        </div>
      )}
    </div>
  );
}
```

The `/api/wallet/balance/` route above is an example of your own backend proxy.

### PHP

```php theme={null}
<?php

$apiKey = getenv('LUMIID_API_KEY');

$url = 'https://api.lumiid.com/v1/wallet/balance/';

$ch = curl_init($url);

curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPGET => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . $apiKey,
        'Accept: application/json'
    ],
    CURLOPT_TIMEOUT => 30
]);

$response = curl_exec($ch);
$httpCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);

if ($response === false) {
    error_log(curl_error($ch));
    curl_close($ch);
    http_response_code(502);
    exit(json_encode(['error' => 'Unable to reach LumiID']));
}

curl_close($ch);

$data = json_decode($response, true);

if ($httpCode !== 200) {
    http_response_code($httpCode);
    echo $response;
    exit;
}

echo json_encode([
    'client' => $data['client']['name'],
    'balance' => $data['balance'],
    'status' => $data['status']
]);
```

### Flutter (Dart)

Install the HTTP package:

```text theme={null}
flutter pub add http
```

Create a wallet service:

```dart theme={null}
import 'dart:convert';
import 'package:http/http.dart' as http;

class LumiIDWalletService {
  final String apiKey;

  LumiIDWalletService({required this.apiKey});

  Future<Map<String, dynamic>> getBalance() async {
    final url = Uri.parse(
      'https://api.lumiid.com/v1/wallet/balance/',
    );

    final response = await http.get(
      url,
      headers: {
        'Authorization': 'Bearer $apiKey',
        'Accept': 'application/json',
      },
    );

    final data = jsonDecode(response.body);

    if (response.statusCode != 200) {
      throw Exception(
        data['error'] ?? 'Unable to retrieve wallet balance',
      );
    }

    return Map<String, dynamic>.from(data);
  }
}
```

Example usage:

```dart theme={null}
final walletService = LumiIDWalletService(
  apiKey: 'YOUR_LUMIID_API_KEY',
);

final wallet = await walletService.getBalance();

print('Client: ${wallet['client']['name']}');
print('Balance: ₦${wallet['balance']}');
```

For production Flutter applications, retrieve the balance through your authenticated backend rather than embedding a permanent secret API key in the application.

## 8. Recommended use cases

* Wallet monitoring: Periodically check available wallet funds.
* Low-balance alerts: Notify administrators when the wallet balance falls below a configured threshold.
* Dashboard integration: Display the current LumiID wallet balance in your application.
* Transaction monitoring: Check available funds before initiating verification requests.

Important: This endpoint retrieves the current wallet balance. It does not fund the wallet, initiate transactions, or reserve funds for verification requests. Authentication is scoped to the organization associated with the API key.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.