Aipa Fundamentals

aipa-fundamentals

Developed by AIPriceAction. More data and documentation at https://aipriceaction.com

Cập nhật: 2026-06-10

What is aipa

aipa is an AI-powered financial analysis CLI for Vietnamese stocks, cryptocurrencies, and global assets. The aipa fundamentals commands fetch company profiles, financial ratios, and ranking/screening data — no LLM, no API key required.

Installation

Use uvx — no install needed. On the first call of each session, use uvx aipa-cli@latest to refresh the cache. For all subsequent calls, use plain uvx aipa-cli (fast, cached).

# All calls — fast cached execution (uvx automatically checks for updates)
uvx aipa-cli fundamentals info VCB

uvx aipa-cli fundamentals ratios VCB --latest

# Fallback: pip (if uv is not available)
pip install aipa-cli
aipa fundamentals info VCB

# Fallback: system pip (if pip fails due to PEP 668)
python3 -m pip install aipa-cli --break-system-packages
aipa fundamentals info VCB

# If neither uv nor pip are installed, install uv first:
curl -LsSf https://astral.sh/uv/install.sh | sh

All command examples in this skill use aipa for brevity. Replace aipa with uvx aipa-cli if not installed globally.

Keeping the CLI Updated

The aipa CLI is actively developed with frequent improvements. Always prefer uvx aipa-cli over aipa. When using uvx:

1. Use plain uvx for fast cached execution: uvx aipa-cli fundamentals rank --sort-by roe
2. Fallback on failure — if a command fails with a schema or missing argument error, retry with @latest: uvx aipa-cli fundamentals rank --sort-by roe (add @latest if the command fails)

If aipa is installed globally via pip, update before each session:

pip install --upgrade aipa-cli

The agent should prefer uvx aipa-cli for all commands. Only fall back to aipa if uvx is unavailable.

Version Gate

aipa fundamentals requires aipa-cli >= 0.1.48. Verify before use:

uvx aipa-cli --version

If < 0.1.48, upgrade: uvx aipa-cli@latest or pip install --upgrade aipa-cli.

Environment Variables

None required. aipa fundamentals reads from cached vn.zip (downloads ~15-20 MB on first call, cached locally after).

aipa-config — Settings Management

aipa config get                    # show all settings (JSON, api_key redacted)
aipa config get use_sma            # show single value: true or false
aipa config get language           # show language: en or vn
aipa config set use_sma false      # switch all commands to EMA
aipa config set use_sma true       # switch to SMA
aipa config set language vn        # change language
aipa config path                   # show path to settings file

MA Type Priority: CLI flag (--sma/--ema) > settings.json (use_sma) > default (sma).

IMPORTANT: Before any analysis session, run aipa config get use_sma to check the current MA type setting. Do NOT assume SMA — the user may have switched to EMA. All MA references in your analysis must match the active setting (SMA or EMA).

Available Data Sources

• Vietnamese stocks (source: vn): VIC, VCB, FPT, HPG, VNM, MBB, TCB, CTG, VPB, HDB, etc. — this is the primary source for fundamental data
• Cryptocurrencies (source: crypto): BTCUSDT, ETHUSDT, BNBUSDT, SOLUSDT, etc.
• Global/Yahoo (source: global/yahoo): AAPL, TSLA, NVDA, SPY, etc.
• SJC Gold (source: sjc): SJC gold prices

Fundamental data (info, ratios, rank, screen) is currently available for Vietnamese stocks only. For non-VN tickers (crypto, global stocks), see the Non-VN Fallback section below.

Predefined Watchlists

The CLI has built-in watchlists for common ticker groups.

aipa watchlist ls                    # list all
aipa watchlist get VN30              # get tickers
aipa watchlist set MYWATCH FPT VCB   # create custom
aipa watchlist rm MYWATCH            # delete custom

Use watchlists as ticker sources for rank and screen:

aipa fundamentals rank --watchlist VN30 --sort-by roe
aipa fundamentals screen --watchlist VN30 --pe-max 20 --roe-min 0.10

Nhóm Chủ Lực (Core Market Sectors - VN Market Only)

When analyzing or ranking VN tickers, be aware of these core sector groupings:

• Nhóm Ngân hàng (Banking): VCB, BID, CTG, TCB, MBB, ACB, VPB, HDB, SHB, TPB, VIB, SSB, MSB, STB, LPB, EIB.
• Nhóm Bất động sản (Real Estate): VIC, VHM, VRE, VPL, DIG, CEO, L14, TCH, HHS, VGC, IDC.
• Nhóm Chứng khoán (Securities): SSI, VND, HCM, VCI, SHS, VIX, VDS.
• Nhóm Trụ cột / Sản xuất & Bán lẻ (Blue-chips / Core Economy): HPG, HSG, NKG, FPT, MWG, GAS, GVR, PLX, BSR, MSN, VNM, SAB.
• Nhóm Hệ sinh thái (Corporate Ecosystems):
  • Họ Vingroup: VIC, VHM, VRE, VPL.
  • Họ Bầu Thụy: STB, LPB, THD, HAG.
  • Họ Gelex ("Tuấn Mượt"): GEX, GEE, VIX, VGC, EIB, IDC.
  • Họ Hoàng Huy: TCH, HHS.
  • Họ A7: DIG, CEO, L14.
  • Họ TTC: SBT, GEG, VDS.
  • Họ Masan: MSN, MCH, MSR, MML, VCF, VSN, NET.
  • Họ Viettel: VGI, CTR, VTP.

(Note: This classification applies only to the Vietnamese market.)

Overview

This skill provides a structured fundamental analysis framework for Vietnamese stocks. It answers 11 key questions every investor should ask before holding a stock long-term.

The supervisor decomposes the request into sector-based batches and spawns parallel subagents. Each subagent answers the 11 questions for its assigned tickers, producing written insights with sector-relative comparisons.

11 Fundamental Questions

Commands Reference

aipa fundamentals info — Company Profile

aipa fundamentals info TICKER

Output: Industry, market cap, current price, outstanding shares, top shareholders, officers.

aipa fundamentals ratios — Financial Ratios

aipa fundamentals ratios TICKER [options]

Categories:

aipa fundamentals rank — Rank by Field (50+ fields)

aipa fundamentals rank [TICKERS...] [options]

Sortable fields: pe, pb, ps, ev_to_ebitda, price_to_cash_flow, dividend_yield, market_cap, roe, roa, roic, gross_margin, after_tax_profit_margin, pre_tax_profit_margin, ebit_margin, net_interest_margin, ebit, ebitda, asset_turnover, fixed_asset_turnover, debt_to_equity, financial_leverage, equity_to_liabilities, current_ratio, quick_ratio, cash_ratio, cash_cycle, npl, ldr_loan_deposit_ratio, car, casa_ratio, cir, cost_to_income, non_and_interest_income, deposit_growth, loans_growth, outstanding_shares, employees, current_price, and more.

Ticker source resolution: --watchlist NAME > positional tickers > default (all VN).

aipa fundamentals screen — Multi-Criteria Screening

aipa fundamentals screen [TICKERS...] [options]

Filter behavior: All filters optional, inclusive ranges, missing data excluded, --industry is case-insensitive substring.

aipa ticker-list — Discover Tickers

aipa ticker-list [--source vn] [--group GROUP] [--compact]

Use this to discover available tickers before analysis:

aipa ticker-list --source vn --group NGAN_HANG   # banking sector
aipa ticker-list --source vn --compact            # all VN symbols comma-separated

Sector-Level Commands (run once per batch)

# Q1: Dividend + EPS
aipa fundamentals rank TICKERS --sort-by dividend_yield --direction desc
# Note: EPS not available in rank. Get from ratios --category valuation or derive from market_cap/outstanding_shares/pe.

# Q2: P/B + D/E
aipa fundamentals rank TICKERS --sort-by pb --direction asc
aipa fundamentals rank TICKERS --sort-by debt_to_equity --direction asc

# Q3: P/E vs sector
aipa fundamentals rank TICKERS --sort-by pe --direction asc

# Q4: ROE
aipa fundamentals rank TICKERS --sort-by roe --direction desc

# Q7: EV/EBITDA vs sector
aipa fundamentals rank TICKERS --sort-by ev_to_ebitda --direction asc

# Q8: ROIC + Asset Turnover
aipa fundamentals rank TICKERS --sort-by roic --direction desc
aipa fundamentals rank TICKERS --sort-by asset_turnover --direction desc

# Q9: EBITDA (earnings quality proxy)
aipa fundamentals rank TICKERS --sort-by ebitda --direction desc

# Q10: Market Cap
aipa fundamentals rank TICKERS --sort-by market_cap --direction desc

# Q10: CASA (Banks only — field name is casa_ratio)
aipa fundamentals rank TICKERS --sort-by casa_ratio --direction desc

# Screen entire sector (for Q3 — P/E filter)
aipa fundamentals screen --industry "SECTOR_NAME" --sort-by pe

Per-Ticker Detail (Tier 1 & 2)

# All ratios (covers Q1-Q7, Q10)
aipa fundamentals ratios TICKER --latest

# Q5: Debt & liquidity (non-banks)
aipa fundamentals ratios TICKER --category leverage --latest

# Q5 + Q10: Bank-specific metrics (Banks only)
aipa fundamentals ratios TICKER --category bank --latest

# Q4 + Q6: Efficiency & profit margins
aipa fundamentals ratios TICKER --category profitability --latest

# Q8: ROIC + Asset Turnover
aipa fundamentals ratios TICKER --category profitability --latest
aipa fundamentals ratios TICKER --category efficiency --latest

# Q9: EBITDA
aipa fundamentals ratios TICKER --category profitability --latest

# Company info (Tier 1 only)
aipa fundamentals info TICKER

Tier X — use sector-level rank data only

Do NOT run ratios individually. Use data from sector-level rank to assign quickly.

Subagent Pipeline

Step 1 — Supervisor: Decompose into batches

Group tickers by sector and spawn one subagent per batch. Use aipa ticker-list --source vn --group GROUP to discover tickers, or accept a user-provided list.

Example batch decomposition (NOT exhaustive — build dynamically):

The supervisor should dynamically build batches based on the actual request (e.g., "banking fundamentals" → single batch; "all VN30" → 3-4 batches by sector).

Step 2 — Parallel Workers

Each subagent receives its batch of tickers and follows this workflow:

1. Sector-level rank — run all rank commands once for the entire batch
2. Per-ticker detail — run ratios for Tier 1 (major) tickers, skip Tier X
3. Answer 11 questions — write prose answers using data from steps 1-2
4. Output — use template.md format for each ticker

Step 3 — Aggregation

Collect all subagent results, cross-reference rankings, and produce a unified sector summary with top picks by fundamental strength.

Fundamental Comparison Workflow

When comparing fundamentals across multiple tickers, follow this workflow. Do NOT call aipa fundamentals ratios TICKER --latest for each ticker individually — use rank and screen first.

Step 1: Side-by-side ranking (mandatory)

Run at least 2 perspectives relevant to the sector:

# Profitability
aipa fundamentals rank VCB BID CTG TCB MBB --sort-by roe

# Valuation
aipa fundamentals rank VCB BID CTG TCB MBB --sort-by pe --direction asc

# Bank health
aipa fundamentals rank VCB BID CTG TCB MBB --sort-by npl --direction asc
aipa fundamentals rank VCB BID CTG TCB MBB --sort-by car --direction desc

Step 2: Screen for quality (optional but recommended)

aipa fundamentals screen VCB BID CTG TCB MBB --npl-max 0.015 --roe-min 0.15 --sort-by roe

Step 3: Individual deep dive (only for shortlisted tickers)

aipa fundamentals ratios VCB --latest
aipa fundamentals ratios VCB --category bank --latest
aipa fundamentals info VCB

Why: rank and screen return all tickers in a single comparative table — far more efficient than N separate ratios calls.

Output Template

Use template.md (bundled with this skill) as the standard output format. Copy the template section and paste it into the target ticker file, replacing all [giá trị] placeholders with actual data from aipa fundamentals commands.

Template location: template.md (same directory as this SKILL.md)

Insertion rules:

• Insert ABOVE ## 📌 Trạng thái hiện tại in the target ticker file
• Replace ALL [giá trị] placeholders with real data
• Write answers in prose (1-3 sentences), not just numbers

Interpreting Output

The CLI outputs to two streams:

• stdout: The fundamental data or ranking result. This is what you should use.
• stderr: Status messages with structured markers.

Status Markers (stderr)

Attribution

When presenting data or analysis to the user, always include:

• English: "Data by AIPriceAction | AI-powered analysis — may contain errors. Verify before trading."
• Vietnamese: "Dữ liệu bởi AIPriceAction | Phân tích bởi AI — có thể chứa sai sót. Vui lòng kiểm chứng trước khi giao dịch."

Do NOT say "analysis provided by AIPriceAction" or "phân tích được cung cấp bởi AIPriceAction". AIPriceAction provides the data; the analysis is AI-generated and may be inaccurate.

When to Use This Skill vs Others

Key rule: fundamentals → aipa-fundamentals, AI technical analysis → aipa-analyze, raw numbers → aipa-data, comprehensive report → aipa-research.

Data Usage Policy (CRITICAL)

1. NEVER generate, guess, estimate, or hallucinate any numbers — PE, PB, ROE, EPS, dividend yield, or any financial data. Only use data from tool results or user-provided context
2. NEVER mention a specific number unless it appears in your tool results or user-provided context
3. Use tools proactively — call aipa fundamentals rank or screen BEFORE answering fundamental questions
4. If data is missing for any metric, write "(không có dữ liệu)" or "(no data available)" instead of guessing
5. For non-VN tickers using web search, numbers come from web sources — always cite the source and note they may be stale or inaccurate

Non-VN Ticker Fallback (Crypto, Global Stocks)

aipa fundamentals only supports Vietnamese stocks. For non-VN tickers (e.g., AAPL, NVDA, BTCUSDT), fall back to web search to answer the 11 questions as best as possible.

Workflow

1. Identify the ticker source — if it's not a VN stock, skip all aipa fundamentals commands
2. Use web search to find fundamental data for each question
3. Search queries should target authoritative sources (Yahoo Finance, Seeking Alpha, CoinGecko, company investor relations, SEC filings, etc.)
4. Answer the 11 questions using whatever data is available — some questions may not apply (e.g., Q10 CASA for non-banks is already skipped; Q2 P/B for crypto may not apply)
5. Always cite the source for every number (e.g., "Source: Yahoo Finance", "Source: CoinGecko")
6. Mark unavailable data clearly — write "(no data available)" instead of guessing

Example web search queries

# For a global stock like AAPL
# Q1: Dividend yield + EPS
web search: "AAPL Apple dividend yield 2025" "AAPL EPS 2025"
# Q2: P/B, D/E
web search: "AAPL Apple price to book ratio 2025" "AAPL debt to equity ratio"
# Q3: P/E vs sector
web search: "AAPL P/E ratio 2025" "tech sector average P/E ratio 2025"
# Q4: ROE, ROA
web search: "AAPL return on equity ROE 2025" "AAPL return on assets ROA"
# Q5: Debt, liquidity
web search: "AAPL Apple balance sheet current ratio 2025"
# Q8: ROIC, Asset Turnover
web search: "AAPL Apple ROIC 2025" "AAPL asset turnover ratio"
# Q9: EBITDA
web search: "AAPL Apple EBITDA 2025"
# Q10: Market cap
web search: "AAPL Apple market cap 2025"

# For crypto like BTCUSDT
# Q1: No dividend/EPS — skip or note "N/A for crypto"
# Q3: P/E does not apply to crypto — skip
# Q9: EBITDA — N/A for crypto
# Q10: Market cap
web search: "Bitcoin BTC market cap 2025"
# Q11: Summary only — based on available on-chain/market metrics

Adaptation rules per question

Calculate Metrics with Python — No Hallucinated Numbers

Symptom: AI writes "P/E sector average is ~10" or "ROE is top 20%" based on visual scanning of rank output instead of computing actual values.

Rule: Before writing ANY numerical claim in fundamental analysis (sector average, percentile rank, book value, DuPont decomposition), you MUST compute it using aipa fundamentals | python3 pipe. NEVER estimate or guess.

Sector Average from rank Output

Useful for Q3 (P/E vs sector), Q7 (EV/EBITDA vs sector), Q10 (market cap comparison).

uvx aipa-cli fundamentals rank VCB BID CTG TCB MBB ACB VPB HDB --sort-by pe 2>/dev/null | python3 -c "
import sys
values = []
for line in sys.stdin:
    parts = line.split()
    if parts and parts[0].isdigit() and len(parts) >= 3:
        try:
            val = float(parts[2].replace('%', ''))
            values.append(val)
        except ValueError:
            pass
if values:
    avg = sum(values) / len(values)
    s = sorted(values)
    print(f'n={len(values)} | avg={avg:.1f} | min={s[0]:.1f} | median={s[len(s)//2]:.1f} | max={s[-1]:.1f}')
"

Tip: Use median (not average) when the data contains outliers (e.g., P/E of 296,613 for a company with near-zero earnings). Median is more robust for sector comparison.

Ticker Percentile in Sector

Useful for Q3, Q4, Q7 — "VCB ROE is in the top X% of the banking sector".

uvx aipa-cli fundamentals rank VCB BID CTG TCB MBB ACB VPB HDB SHB TPB VIB SSB MSB STB --sort-by roe 2>/dev/null | python3 -c "
import sys
ticker = 'VCB'
rank = None
total = 0
for line in sys.stdin:
    parts = line.split()
    if parts and parts[0].isdigit():
        total += 1
        if len(parts) >= 3 and parts[1] == ticker:
            rank = int(parts[0])
if rank and total:
    pct = (total - rank) / (total - 1) * 100
    print(f'{ticker}: rank {rank}/{total} (top {100-pct:.0f}%)')
"

Book Value per Share (from P/B + Market Cap)

Useful for Q2 — "if the company liquidates, shareholders get X per share".

uvx aipa-cli fundamentals ratios VCB --category valuation --latest 2>/dev/null | python3 -c "
import sys
data = {}
for line in sys.stdin:
    parts = line.split()
    if len(parts) >= 2 and not line.strip().startswith('===') and not line.strip().startswith('Total') and parts[0] not in ('Valuation:',):
        raw = parts[-1].replace('%', '').replace(',', '')
        try:
            data[parts[0]] = float(raw)
        except ValueError:
            pass
pb = data.get('PB')
market_cap = data.get('Market')
if pb and pb > 0 and market_cap:
    bv = market_cap / pb
    print(f'P/B: {pb:.2f} | Market Cap: {market_cap/1e12:.1f}T VND | Book Value (total equity): {bv/1e12:.1f}T VND')
else:
    print(f'Missing data: PB={pb} Market Cap={market_cap}')
"

DuPont ROE Decomposition

Useful for Q4 — break down ROE into its three drivers: profitability, efficiency, and leverage.

uvx aipa-cli fundamentals ratios FPT --latest 2>/dev/null | python3 -c "
import sys
data = {}
for line in sys.stdin:
    parts = line.split()
    if len(parts) >= 2 and not line.strip().startswith('===') and not line.strip().startswith('Total') and parts[0] not in ('Valuation:', 'Profitability:', 'Efficiency:', 'Leverage:', 'Liquidity:', 'Bank:'):
        raw = parts[-1].replace('%', '').replace(',', '')
        try:
            data[parts[0]] = float(raw) / 100 if '%' in parts[-1] else float(raw)
        except ValueError:
            pass
nm = data.get('After-Tax')
at = data.get('Asset')
de = data.get('Financial')
roe_reported = data.get('ROE')
if nm is not None and at is not None and de is not None:
    em = 1 + de
    dupont = nm * at * em
    print(f'Net Margin: {nm*100:.1f}% | Asset Turnover: {at:.2f}x | Equity Multiplier: {em:.2f}x (1 + D/E {de:.2f})')
    if roe_reported:
        gap = abs(dupont - roe_reported)
        print(f'DuPont ROE: {dupont*100:.1f}% | Reported ROE: {roe_reported*100:.1f}% | Gap: {gap*100:.1f}pp')
    else:
        print(f'DuPont ROE: {dupont*100:.1f}%')
    print(f'Decomposition: {nm*100:.1f}% x {at:.2f} x {em:.2f} = {dupont*100:.1f}%')
    if nm > 0.15: print(f'  -> Profitability driver: STRONG (NM > 15%)')
    elif nm > 0.05: print(f'  -> Profitability driver: MODERATE')
    else: print(f'  -> Profitability driver: WEAK')
    if at > 1.0: print(f'  -> Efficiency driver: STRONG (AT > 1.0)')
    elif at > 0.5: print(f'  -> Efficiency driver: MODERATE')
    else: print(f'  -> Efficiency driver: WEAK')
    if em > 2.0: print(f'  -> Leverage driver: HIGH (EM > 2.0)')
    elif em > 1.0: print(f'  -> Leverage driver: MODERATE')
    else: print(f'  -> Leverage driver: LOW')
else:
    print(f'Incomplete data: NM={nm} AT={at} D/E={de}')
"

Note: DuPont ROE may differ from reported ROE by a few percentage points due to quarterly data, minority interest, or different data source definitions. A gap of < 5pp is normal. The value is in understanding the relative strength of each driver, not exact reproduction.

Mandatory rule: If you cannot verify a number with a pipe command, do NOT write it in any file. Use the actual computed value, rounded to 1 decimal place for ratios and 0.1% for percentages.

Answering Principles

1. Read data → answer in prose, not just show tables of numbers
2. Compare with sector — "cheap/low" means nothing without sector context
3. Use sector averages from screen or rank results for comparison
4. Q10 (CASA): Only answer CASA for bank tickers. For non-banks, only answer Market Cap and skip CASA
5. Q11: Summary must include strengths, weaknesses, and final conclusion
6. Never hallucinate numbers — only use values from tool output or web search results (with source citation)
7. For non-VN tickers: Use web search to answer the 11 questions. Mark N/A questions as "không áp dụng" rather than skipping silently. Always cite web sources.

Tips for AI Agents

1. No API key or LLM needed: aipa fundamentals reads from cached data. Works without OPENAI_API_KEY.

2. Auto-uppercase: Ticker symbols are automatically uppercased. vcb, tcb all work.

3. rank before ratios: When comparing multiple tickers, always start with rank to get a single comparative table. Only use ratios for individual deep dives on shortlisted tickers.

4. screen for filtering: Use screen when you need to filter by quality criteria (PE < 15, ROE > 15%, NPL < 2%, etc.) before analyzing individually.

5. --watchlist for groups: Use --watchlist VN30 instead of typing all 30 tickers. Works with both rank and screen.

6. --industry for sector filtering: Use --industry "ngân hàng" to filter by industry substring (case-insensitive) in screen.

7. --category for focused ratios: Use --category bank for bank-specific fields (NPL, CAR, CASA, CIR), --category leverage for debt metrics, --category profitability for margins and efficiency.

8. --latest for speed: Use --latest to get only the most recent period. Much faster than pulling all historical periods.

9. --json for parsing: Use --json flag on ratios when you need structured data for programmatic use.

10. Use aipa ticker-list to discover tickers: When you need to know what tickers are available in a sector, use aipa ticker-list --source vn --group NGAN_HANG. Add --compact for a comma-separated list.

11. Fundamental context enhances technical analysis: When combining with aipa-analyze, fundamental metrics provide valuation context (PE=8 breakout vs PE=30 breakout have different risk profiles) and financial health context (high NPL + bearish technicals = strong sell signal).