Getting Started
Relevant source files
The following files were used as context for generating this wiki page:
The MBBank library is a lightweight, unofficial Python API wrapper designed for interacting with "Military Commercial Joint Stock Bank" (MBBank) personal accounts. It provides both synchronous and asynchronous interfaces to perform banking operations such as checking balances, retrieving transaction histories, and making transfers.
The library handles complex authentication requirements, including automated CAPTCHA solving via OCR and request encryption using WebAssembly (WASM) modules to mirror the official web portal's security mechanisms.
Sources: pyproject.toml:5-10, mbbank/init.py:1-15
Installation and Prerequisites
Requirements
The library requires Python 3.10+ due to the use of advanced type hinting and pattern matching. It depends on several core packages for networking, data validation, and security:
| Dependency | Purpose |
|---|---|
requests | Synchronous HTTP requests |
aiohttp | Asynchronous HTTP requests |
wasmtime | Running WASM for request encryption |
mb-capcha-ocr | CAPTCHA image processing |
pydantic | Data validation and response modeling |
Pillow | Image handling |
Sources: pyproject.toml:12-25, CONTRIBUTING.md:10-15
Installation
You can install the library and its development tools using uv (recommended) or pip:
# Using uv
uv sync --group dev
# Using pip
pip install -e ".[dev]"
Sources: CONTRIBUTING.md:17-25
Core Architecture
The library is structured around a base class that manages shared state, with specialized implementations for synchronous and asynchronous workflows.
The MBBankBase class stores credentials and maintains the deviceIdCommon and sessionId required for all API calls.
Sources: mbbank/base/mbbank.py:7-50, mbbank/sync/mbbank.py:44-55, mbbank/aio/mbbank.py:44-55
Authentication Flow
Authentication is an automated multi-step process. When a session is expired or missing, the library automatically triggers the authentication flow during a request.
- CAPTCHA Retrieval: Fetches a base64 encoded image from MBBank.
- OCR Processing: Uses the
CapchaOCRclass to convert the image to text. - WASM Encryption: Encrypts the login payload (username, MD5 password, CAPTCHA) using the bank's WebAssembly module.
- Login: Submits the encrypted data to the
/doLoginendpoint.
Basic Usage
Synchronous Client
The standard MBBank class is used for simple scripts and synchronous applications.
from mbbank import MBBank
mb = MBBank(username="your_user", password="your_password")
# Session is established automatically on first call
balance = mb.getBalance()
for account in balance.acct_list:
print(f"Account: {account.acctNo} | Balance: {account.currentBalance}")
Sources: mbbank/init.py:27-45, examples/transaction_history.py:7-15
Asynchronous Client
For high-concurrency applications, use MBBankAsync. It utilizes aiohttp and runs CPU-bound WASM encryption in a thread pool to avoid blocking the event loop.
import asyncio
from mbbank import MBBankAsync
async def main():
async with MBBankAsync(username="user", password="pass") as mb:
info = await mb.userinfo()
print(f"Welcome, {info.cust.nm}")
asyncio.run(main())
Sources: mbbank/aio/mbbank.py:44-80, mbbank/init.py:20-22
Common Operations
| Method | Description | Return Model |
|---|---|---|
getBalance() | List all accounts and their current balances. | BalanceResponseModal |
getTransactionAccountHistory(...) | Fetch history for a date range (max 3 months). | TransactionHistoryResponseModal |
getCardList() | Retrieve all associated debit/credit cards. | CardListResponseModal |
getBankList() | Get a list of supported banks for transfers. | BankListResponseModal |
getSavingList() | List all fixed-term saving accounts. | SavingListResponseModal |
Sources: mbbank/sync/mbbank.py:180-260, mbbank/modals/init.py:1-40
Summary
To get started with the MBBank library, ensure you have Python 3.10+ and install the dependencies. The library abstracts the complexities of MBBank's web encryption and CAPTCHA requirements, allowing developers to focus on banking logic using either the MBBank (Sync) or MBBankAsync (Async) classes. Detailed examples for specific features like money transfers and history retrieval can be found in the examples/ directory of the repository.