> ## 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 Node.js / TypeScript 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.

***

## Account Service

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

### Get Wallet Info

```typescript theme={null}
// Optionally scope to a specific EVM chain
const wallet = await monei.account.me(56); // BSC chain ID
console.log(wallet.balance, wallet.address);
```

### Create Virtual Account

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

```typescript theme={null}
const account = await monei.account.createVirtualAccount({
  subWalletId: 'sub-wallet-id',
});

console.log(account.accountNumber); // e.g. "0123456789"
console.log(account.bankName);      // e.g. "Wema Bank"
```

***

## Deposit Service

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

### Initialize a Deposit

```typescript theme={null}
import { DEPOSIT_METHOD } from 'monei-sdk';

const deposit = await monei.deposit.initialize(
  DEPOSIT_METHOD.BANK_TRANSFER,
  {
    amount: 5000,          // Amount in kobo
    currency: 'NGN',
    subWalletId: 'sub-wallet-id',
  }
);

console.log(deposit.reference, deposit.paymentUrl);
```

### Deposit with Saved Payment Method

```typescript theme={null}
const deposit = await monei.deposit.withPaymentMethod({
  amount: 5000,
  currency: 'NGN',
  paymentMethodId: 'pm-id',
  subWalletId: 'sub-wallet-id',
});

console.log(deposit.reference, deposit.status);
```

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

```typescript theme={null}
await 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.

```typescript theme={null}
const link = await monei.deposit.generatePaymentLink({
  amount: 10000,
  currency: 'NGN',
  description: 'Invoice #42',
  subWalletId: 'sub-wallet-id',
});

console.log(link.url);
```

### Check Deposit Status

```typescript theme={null}
const status = await monei.deposit.getStatus(deposit.reference);
console.log(status.status); // "pending" | "successful" | "failed"
```

***

## Payout Service

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

### Bank Transfer

```typescript theme={null}
const transfer = await monei.payout.bankTransfer({
  amount: 5000,
  bankCode: 'GTBINGLA',
  accountNumber: '0123456789',
  accountName: 'John Doe',
  narration: 'Payment for services',
  subWalletId: 'sub-wallet-id',
});

console.log(transfer.reference, transfer.status);
```

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

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

```typescript theme={null}
const transfer = await monei.payout.peerTransfer({
  amount: 2000,
  recipientTag: '@john',   // or email / user ID
  narration: 'Lunch split',
  subWalletId: 'sub-wallet-id',
});

console.log(transfer.reference, transfer.status);
```

***

## Wallet Utility Service

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

### Get All Banks

```typescript theme={null}
const { banks } = await monei.utility.getBanks();
banks.forEach(b => console.log(b.name, b.code));
```

### Verify Bank Account

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

```typescript theme={null}
const verified = await monei.utility.verifyBankAccount({
  accountNumber: '0123456789',
  bankCode: 'GTBINGLA',
});

console.log(verified.accountName); // "JOHN ADEWALE DOE"
```

***

## Working with Response Objects

All methods return objects with property access:

```typescript theme={null}
// Account response
const wallet = await monei.account.me(56);
console.log(wallet.balance);      // Wallet balance
console.log(wallet.address);      // Wallet address
console.log(wallet.currency);     // Currency code

// Virtual account response
const account = await monei.account.createVirtualAccount({...});
console.log(account.accountNumber);  // Virtual account number
console.log(account.bankName);       // Bank name
console.log(account.accountName);    // Account holder name

// Deposit response
const deposit = await monei.deposit.initialize(...);
console.log(deposit.reference);   // Deposit reference
console.log(deposit.paymentUrl);  // Payment URL
console.log(deposit.status);      // Deposit status

// Payment link response
const link = await monei.deposit.generatePaymentLink({...});
console.log(link.url);            // Payment link URL
console.log(link.reference);      // Payment reference

// Bank transfer response
const transfer = await monei.payout.bankTransfer({...});
console.log(transfer.reference);  // Transfer reference
console.log(transfer.status);     // Transfer status
console.log(transfer.fee);        // Transfer fee

// Peer transfer response
const peerTransfer = await monei.payout.peerTransfer({...});
console.log(peerTransfer.reference);  // Transfer reference
console.log(peerTransfer.status);     // Transfer status

// Banks response
const { banks } = await monei.utility.getBanks();
banks.forEach(bank => {
  console.log(bank.name);   // Bank name
  console.log(bank.code);   // Bank code
});

// Verified account response
const verified = await monei.utility.verifyBankAccount({...});
console.log(verified.accountName);   // Verified account name
console.log(verified.accountNumber); // Account number
console.log(verified.bankName);      // Bank name
```

***

## Error Handling

All wallet service calls may throw an error if the request fails.

```typescript theme={null}
import { MoneiError } from 'monei-sdk';

try {
  const wallet = await monei.account.me(56);
  console.log(wallet.balance);
} catch (error) {
  if (error instanceof MoneiError) {
    console.error(error.statusCode);  // HTTP status code
    console.error(error.message);     // Error message
    console.error(error.code);        // Error code
  }
}
```

***

## Service Overview

| Service     | Method                          | Description                       |
| ----------- | ------------------------------- | --------------------------------- |
| **Account** | `me(chainId?)`                  | Get wallet info                   |
|             | `createVirtualAccount(options)` | Create virtual bank account       |
| **Deposit** | `initialize(method, data)`      | Initialize a deposit              |
|             | `withPaymentMethod(data)`       | Deposit with saved payment method |
|             | `authorize(data)`               | Authorize deposit with OTP        |
|             | `generatePaymentLink(data)`     | Generate payment link             |
|             | `getStatus(reference)`          | Check deposit status              |
| **Payout**  | `bankTransfer(data)`            | Send bank transfer                |
|             | `peerTransfer(data)`            | Send peer-to-peer transfer        |
| **Utility** | `getBanks()`                    | Get all supported banks           |
|             | `verifyBankAccount(data)`       | 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 property access

***