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

# Wallet Services

> Manage wallets, check balances, transfer funds, and track transactions using the Monei Python SDK.

# Overview

The `Wallet Services` provides a comprehensive set of services for managing wallets, checking balances, transferring funds, and tracking transactions.

Included services:

* **Account** — view wallet info and create virtual accounts
* **Deposit** — fund Naira wallet via multiple channels
* **Payout** — send Naira to bank accounts or other Monei users
* **Utility** — look up banks and verify account numbers

All services require a properly configured `MoneiClient` instance.

> **Note**: All methods return response objects with attributes accessible via dot notation (e.g., `wallet.balance`, `deposit.reference`).

***

## Account Service

`monei.account` provides methods to view wallet balances and create virtual bank accounts for deposits.

### Get Wallet Info

```python theme={null}
# Optionally scope to a specific EVM chain
wallet = monei.account.me(56)  # BSC chain ID
print(wallet.balance, wallet.address)
```

### Create Virtual Account

Virtual accounts give users a dedicated Nigerian bank account number to fund their Naira wallet.

```python theme={null}
account = monei.account.create_virtual_account(
    sub_wallet_id="sub-wallet-id"
)

print(account.account_number)  # e.g. "0123456789"
print(account.bank_name)       # e.g. "Wema Bank"
```

***

## Deposit Service

`monei.deposit` provides methods to fund the Naira wallet via multiple channels.

### Initialize a Deposit

```python theme={null}
from monei import DEPOSIT_METHOD

deposit = monei.deposit.initialize(
    DEPOSIT_METHOD.BANK_TRANSFER,
    amount=5000,           # Amount in kobo
    currency="NGN",
    sub_wallet_id="sub-wallet-id"
)

print(deposit.reference, deposit.payment_url)
```

### Deposit with Saved Payment Method

```python theme={null}
deposit = monei.deposit.with_payment_method(
    amount=5000,
    currency="NGN",
    payment_method_id="pm-id",
    sub_wallet_id="sub-wallet-id"
)

print(deposit.reference, deposit.status)
```

### Authorize a Deposit (OTP / 3DS)

```python theme={null}
monei.deposit.authorize(
    reference=deposit.reference,
    otp="123456"
)
```

### Generate a Payment Link

Share a payment link so anyone can fund your wallet without an account.

```python theme={null}
link = monei.deposit.generate_payment_link(
    amount=10000,
    currency="NGN",
    description="Invoice #42",
    sub_wallet_id="sub-wallet-id"
)

print(link.url)
```

### Check Deposit Status

```python theme={null}
status = monei.deposit.get_status(deposit.reference)
print(status.status)  # "pending" | "successful" | "failed"
```

***

## Payout Service

`monei.payout` provides methods to send Naira to bank accounts or other Monei users.

### Bank Transfer

```python theme={null}
transfer = monei.payout.bank_transfer(
    amount=5000,
    bank_code="GTBINGLA",
    account_number="0123456789",
    account_name="John Doe",
    narration="Payment for services",
    sub_wallet_id="sub-wallet-id"
)

print(transfer.reference, transfer.status)
```

### Peer Transfer (Monei-to-Monei)

Send funds instantly to another Monei user's wallet — zero fees, instant settlement.

```python theme={null}
transfer = monei.payout.peer_transfer(
    amount=2000,
    recipient_tag="@john",   # or email / user ID
    narration="Lunch split",
    sub_wallet_id="sub-wallet-id"
)

print(transfer.reference, transfer.status)
```

***

## Wallet Utility Service

`monei.utility` provides methods to look up banks and verify account numbers before sending.

### Get All Banks

```python theme={null}
banks_response = monei.utility.get_banks()

for bank in banks_response.banks:
    print(bank.name, bank.code)
```

### Verify Bank Account

Always call this before a bank transfer to confirm the account name matches.

```python theme={null}
verified = monei.utility.verify_bank_account(
    account_number="0123456789",
    bank_code="GTBINGLA"
)

print(verified.account_name)  # "JOHN ADEWALE DOE"
```

***

## Working with Response Objects

All methods return objects with attribute access:

```python theme={null}
# Account response
wallet = monei.account.me(56)
print(wallet.balance)      # Wallet balance
print(wallet.address)      # Wallet address
print(wallet.currency)     # Currency code

# Virtual account response
account = monei.account.create_virtual_account(sub_wallet_id="...")
print(account.account_number)  # Virtual account number
print(account.bank_name)       # Bank name
print(account.account_name)    # Account holder name

# Deposit response
deposit = monei.deposit.initialize(DEPOSIT_METHOD.BANK_TRANSFER, ...)
print(deposit.reference)   # Deposit reference
print(deposit.payment_url) # Payment URL
print(deposit.status)      # Deposit status

# Payment link response
link = monei.deposit.generate_payment_link(...)
print(link.url)            # Payment link URL
print(link.reference)      # Payment reference

# Bank transfer response
transfer = monei.payout.bank_transfer(...)
print(transfer.reference)  # Transfer reference
print(transfer.status)     # Transfer status
print(transfer.fee)        # Transfer fee

# Peer transfer response
peer_transfer = monei.payout.peer_transfer(...)
print(peer_transfer.reference)  # Transfer reference
print(peer_transfer.status)     # Transfer status

# Banks response
banks_response = monei.utility.get_banks()
for bank in banks_response.banks:
    print(bank.name)   # Bank name
    print(bank.code)   # Bank code

# Verified account response
verified = monei.utility.verify_bank_account(...)
print(verified.account_name)   # Verified account name
print(verified.account_number) # Account number
print(verified.bank_name)      # Bank name
```

***

## Error Handling

All wallet service calls may raise an exception if the request fails.

```python theme={null}
from monei import MoneiError

try:
    wallet = monei.account.me(56)
    print(wallet.balance)
except MoneiError as err:
    print(err.status_code)  # HTTP status code
    print(err.message)      # Error message
    print(err.code)         # Error code
```

***

## Service Overview

| Service     | Method                                                                                     | Description                       |
| ----------- | ------------------------------------------------------------------------------------------ | --------------------------------- |
| **Account** | `me(chain_id=None)`                                                                        | Get wallet info                   |
|             | `create_virtual_account(sub_wallet_id)`                                                    | Create virtual bank account       |
| **Deposit** | `initialize(method, amount, currency, sub_wallet_id)`                                      | Initialize a deposit              |
|             | `with_payment_method(amount, currency, payment_method_id, sub_wallet_id)`                  | Deposit with saved payment method |
|             | `authorize(reference, otp)`                                                                | Authorize deposit with OTP        |
|             | `generate_payment_link(amount, currency, description, sub_wallet_id)`                      | Generate payment link             |
|             | `get_status(reference)`                                                                    | Check deposit status              |
| **Payout**  | `bank_transfer(amount, bank_code, account_number, account_name, narration, sub_wallet_id)` | Send bank transfer                |
|             | `peer_transfer(amount, recipient_tag, narration, sub_wallet_id)`                           | Send peer-to-peer transfer        |
| **Utility** | `get_banks()`                                                                              | Get all supported banks           |
|             | `verify_bank_account(account_number, bank_code)`                                           | Verify bank account details       |

***

## Notes

* All methods require a properly configured `MoneiClient` instance with authentication
* Amounts are in kobo (1 NGN = 100 kobo)
* Virtual accounts are only available for Naira wallets
* Bank transfers require verification before processing
* All responses are strongly typed objects with attribute access

***