# How to Use financial_rigor.py to Verify Market Cap in HKD, USD, and CNY

> Learn how to use financial_rigor.py to verify market cap in HKD USD and CNY. This guide shows you how to compare calculated and reported market caps with precision.

- Repository: [Xbt Lin/ai-berkshire](https://github.com/xbtlin/ai-berkshire)
- Tags: how-to-guide
- Published: 2026-07-28

---

**The `verify_market_cap` function in [`tools/financial_rigor.py`](https://github.com/xbtlin/ai-berkshire/blob/main/tools/financial_rigor.py) validates market capitalization by comparing the product of share price and total shares against the reported cap using high-precision `Decimal` arithmetic, accepting any currency code as a free-form string without performing automatic FX conversion.**

The [`financial_rigor.py`](https://github.com/xbtlin/ai-berkshire/blob/main/financial_rigor.py) module in the **xbtlin/ai-berkshire** repository provides a robust CLI and Python API for financial verification tasks. This tool eliminates floating-point errors by using exact decimal calculations when checking whether a company's reported market capitalization matches the mathematical product of its share price and outstanding shares.

## How verify_market_cap Works

The core verification logic resides in **`verify_market_cap`** at [lines 74-90](https://github.com/xbtlin/ai-berkshire/blob/main/tools/financial_rigor.py#L74-L90) of [`tools/financial_rigor.py`](https://github.com/xbtlin/ai-berkshire/blob/main/tools/financial_rigor.py). 

The function performs four critical steps:

1. **Normalizes inputs** – All numeric arguments are converted to exact `Decimal` values via the `exact()` helper to avoid floating-point drift
2. **Computes theoretical cap** – Calculates `price × shares` using the high-precision decimal context (`_CTX`)
3. **Calculates deviation** – Measures the percentage difference between the computed value and the reported market cap
4. **Returns validation status** – Returns `True` if deviation is ≤ 5%, otherwise `False`, while printing a detailed report that includes the supplied currency symbol

Because the **`currency`** parameter accepts any free-form string, the same routine works for HKD, USD, CNY, or any other monetary unit. The tool does **not** perform automatic FX conversion—all inputs must be expressed in the same currency unit.

## Command-Line Usage for Multi-Currency Verification

The CLI entry point ([lines 95-103](https://github.com/xbtlin/ai-berkshire/blob/main/tools/financial_rigor.py#L95-L103)) parses the `--currency` flag and forwards it directly to the verification function. This design allows you to validate market caps across different currencies without modifying the underlying logic.

### Verifying Market Cap in Hong Kong Dollars (HKD)

```bash
python3 tools/financial_rigor.py verify-market-cap \
    --price 510 \
    --shares 9.11e9 \
    --reported 4.65e12 \
    --currency HKD

```

Output:

```

市值验算 (Market Cap Verification)
  股价 (Price):       510 HKD
  总股本 (Shares):    9.11B
  计算市值:           4.65T HKD
  报告市值:           4.65T HKD
  偏差:               0.00%
  ✅ 验证通过, 偏差仅 0.00%

```

### Verifying Market Cap in US Dollars (USD)

```bash
python3 tools/financial_rigor.py verify-market-cap \
    --price 65.2 \
    --shares 9.11e9 \
    --reported 5.94e11 \
    --currency USD

```

### Verifying Market Cap in Chinese Yuan (CNY)

```bash
python3 tools/financial_rigor.py verify-market-cap \
    --price 3510 \
    --shares 9.11e9 \
    --reported 3.20e13 \
    --currency CNY

```

## Programmatic Usage in Python

You can import the module directly for use in data pipelines or Jupyter notebooks:

```python
from tools import financial_rigor as fr

# All values must be in the same currency (CNY example)

valid = fr.verify_market_cap(
    price=3510,
    shares=9.11e9,
    reported_cap=3.20e13,
    currency="CNY"
)

if valid:
    print("Market cap check passed.")
else:
    print("Market cap discrepancy detected.")

```

## Handling Cross-Currency Comparisons

The tool deliberately avoids external dependencies for FX conversion. If your price and reported market cap are denominated in different currencies (e.g., price in HKD but reported cap in USD), you must convert them beforehand:

```python
from forex_python.converter import CurrencyRates
from tools import financial_rigor as fr

c = CurrencyRates()
rate_hkd_usd = c.get_rate('HKD', 'USD')   # e.g. 0.128

price_hkd = 510
price_usd = price_hkd * rate_hkd_usd
shares = 9.11e9
reported_usd = 4.65e12 * rate_hkd_usd

fr.verify_market_cap(
    price=price_usd,
    shares=shares,
    reported_cap=reported_usd,
    currency="USD"
)

```

## Summary

- The **`verify_market_cap`** function in [`tools/financial_rigor.py`](https://github.com/xbtlin/ai-berkshire/blob/main/tools/financial_rigor.py) (lines 74-90) performs high-precision validation using `Decimal` arithmetic to prevent floating-point errors
- The CLI accepts any currency string via **`--currency`** but requires that price, shares, and reported cap share the same monetary unit
- **No automatic FX conversion** is performed; normalize currencies externally before verification whenever cross-currency comparisons are needed
- The function returns a **Boolean** (`True` if deviation ≤ 5%) and prints a detailed diagnostic report including the currency symbol
- The module can be imported as a library or invoked from the command line ([lines 95-103](https://github.com/xbtlin/ai-berkshire/blob/main/tools/financial_rigor.py#L95-L103))

## Frequently Asked Questions

### Does financial_rigor.py automatically convert between HKD, USD, and CNY?

No, the tool does not perform automatic FX conversion. You must convert all values to a common currency before passing them to `verify_market_cap`. The `currency` parameter is purely for display and labeling purposes in the output report.

### What is the acceptable deviation threshold for market cap verification?

The function considers a deviation of **≤ 5%** between the calculated (`price × shares`) and reported market cap as valid, returning `True`. Larger discrepancies return `False`, indicating potential data inconsistencies or rounding errors that warrant investigation.

### Why does the tool use Decimal instead of float for calculations?

The `exact()` helper function converts inputs to `Decimal` objects under a high-precision context (`_CTX`) to avoid floating-point drift errors. This is critical for financial calculations where precision losses from binary floating-point representation could invalidate verification results.

### Can I use financial_rigor.py as a library in my own Python scripts?

Yes, you can import `tools.financial_rigor` and call `verify_market_cap(price, shares, reported_cap, currency)` directly. This makes the verification logic reusable in data pipelines, quantitative analysis workflows, or automated testing suites outside the CLI environment.