Home
Relevant source files
The following files were used as context for generating this wiki page:
The mbbank-lib is an unofficial, lightweight Python API wrapper designed for interacting with Military Commercial Joint Stock Bank (MBBank) personal accounts. It provides a structured interface to automate banking tasks such as checking balances, retrieving transaction histories, and performing internal or external money transfers. Sources: pyproject.toml:5-7, mbbank/init.py:1-5
The library is built to support both synchronous and asynchronous execution environments, leveraging Pydantic for robust data validation and wasmtime for executing the bank's proprietary encryption logic within WebAssembly. Sources: mbbank/init.py:10-15, pyproject.toml:17-25
Core Architecture
The system follows a hierarchical inheritance pattern where a base class provides shared utilities, headers, and device identification logic, which is then specialized for blocking (sync) or non-blocking (async) operations.
Class Hierarchy
The relationship between the core library classes is shown in the diagram below:
The MBBankBase class initializes common attributes like deviceIdCommon using a unique string format based on the current timestamp. Sources: mbbank/base/mbbank.py:10-70, mbbank/sync/mbbank.py:40-45, mbbank/aio/mbbank.py:46-51
Key System Components
| Component | Description | Relevant Files |
|---|---|---|
| Sync Client | Uses requests for synchronous API interaction. | mbbank/sync/mbbank.py |
| Async Client | Uses aiohttp for asynchronous API interaction. | mbbank/aio/mbbank.py |
| Wasm Helper | Handles credential encryption using the bank's .wasm module. | mbbank/wasm_helper/__init__.py |
| Captcha OCR | Processes banking captcha images via mb-capcha-ocr. | mbbank/base/mbbank.py |
| Response Modals | Pydantic models for structured API responses. | mbbank/modals/ |
Authentication and Security Flow
Accessing MBBank's internal APIs requires a multi-step authentication process involving automated captcha solving and WebAssembly-based payload encryption.
Authentication Process Flow
The following diagram illustrates the internal logic used to establish a valid sessionId:
Citations:
- Captcha Handling: The client fetches a Base64 captcha image and uses an
ocr_classto extract text. Sources: mbbank/sync/mbbank.py:117-145, mbbank/aio/mbbank.py:115-135 - Encryption: Login payloads are encrypted using the
wasm_encryptfunction, which replicates a Go-based environment to run the bank's WebAssembly module. Sources: mbbank/wasm_helper/init.py:317-340 - Retry Logic: The system defaults to 30 retries for captcha failures (error code
GW283). Sources: mbbank/sync/mbbank.py:205-220
Functional Capabilities
The library exposes various endpoints through the MBBank and MBBankAsync classes.
Account and Financial Services
- Balance Inquiries: Retrieves balances for all main and sub-accounts. Sources: mbbank/sync/mbbank.py:257-270
- Transaction History: Fetches transactions for a specific account within a date range (maximum 3 months). Sources: mbbank/sync/mbbank.py:226-255
- Interest Rates: Provides current saving interest rates for currencies like VND. Sources: mbbank/sync/mbbank.py:289-307
- Savings Management: Lists all saving accounts and detailed information for specific accounts (
OSAorSBA). Sources: mbbank/sync/mbbank.py:346-378
Transfer Services
The library supports complex transfer workflows through the TransferContext.
Configuration and Requirements
System Requirements
- Python: 3.10 or higher. Sources: pyproject.toml:11
- Core Dependencies:
wasmtime: Execution of security modules.pydantic: Data modeling.aiohttp/requests: Network communication.mb-capcha-ocr: Captcha solving.
Sources: pyproject.toml:17-25
Default Settings
The MBBankBase class defines standard headers and identification strings used across all requests.
# mbbank/base/mbbank.py:19-35
HEADERS_DEFAULT = {
"Accept": "application/json, text/plain, */*",
"App": "MB_WEB",
"Origin": "https://online.mbbank.com.vn",
"Referer": "https://online.mbbank.com.vn/pl/login?returnUrl=%2F",
"User-Agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) ..."
}
Summary
The "Home" of the MBBank project is centered around the MBBank and MBBankAsync clients. These clients abstract the complexities of the MBBank web API, including automated session management, WebAssembly-based security protocols, and structured data handling. By providing both sync and async versions, the library allows developers to integrate banking features into a wide range of Python applications, from simple automation scripts to high-concurrency web services. Sources: mbbank/init.py:1-40, mbbank/sync/mbbank.py:40-50