/finlab

name: finlab
description: Comprehensive guide for FinLab quantitative trading package across global stock markets (TW, US, KR, JP, HK; both single-name equities and ETFs/funds). Use when working with trading strategies, backtesting, stock data, FinLabDataFrame, factor analysis, stock selection, or when the user mentions FinLab, trading, quant trading, US equity, S&P 500 / NASDAQ 100, SPY / QQQ, sector or leveraged ETFs, ETF rotation, 美股, or stock market analysis. Includes data access, strategy development, backtesting workflows, best practices, and US-market specifics (data availability map, filing-date-aligned quarterly fundamentals, US universe construction, USMarket vs. USFundMarket defaults, and ETF backtesting).
compatibility: Requires Python 3.10+ and uv package manager (https://docs.astral.sh/uv/)

FinLab Quantitative Trading Package

Prerequisites

**Before running any FinLab code, verify these in order:**

1. **uv is installed** (Python package manager):

   uv --version

If uv is not installed, tell the user to install it.

After installing, ensure `uv` is on PATH:

   source $HOME/.local/bin/env 2>/dev/null  # Add uv to current shell

2. **FinLab is installed via uv** (requires >= 2.0.0):

   uv python install 3.12  # Ensure Python is available (skip if already installed)
   uv pip install --system "finlab>=2.0.0" 2>/dev/null || uv pip install "finlab>=2.0.0"

**Or use `uv run` for zero-setup execution** (recommended for one-off scripts):

   uv run --with "finlab" python3 script.py

`uv run --with` auto-creates a temporary environment with dependencies — no venv management needed.

**Prefer zero-install?** Run notebooks directly in [FinLab Studio](https://studio.finlab.finance) — a hosted Jupyter environment with `finlab` preinstalled and your API token already wired up.

3. **API Token is set** (required - finlab will fail without it):

**If no token, use finlab's built-in login** (available in >= 1.5.9, improved Firebase flow in v1.5.11):

   import finlab
   finlab.login()  # Opens browser for Google OAuth, saves token automatically

This handles the full OAuth flow (browser login, token retrieval, `.env` storage) automatically. Tokens are bound to a FinLab account at [finlab.finance](https://finlab.finance) — `finlab.login()` provisions one on first use.

Language

**Respond in the user's language.** If user writes in Chinese, respond in Chinese. If in English, respond in English.

Market Support

FinLab supports TW (default), US, KR, JP, HK, plus Taiwan emerging (`rotc`) and Taiwan convertible bonds (`tw_cb`). Pick the market once per session with `data.set_market(<code>)`; generic dataset names like `price:收盤價` or `monthly_revenue:當月營收` resolve to the active market's tables, so strategy code is written the same way across markets. `data.set_market('rotc')` *(v2.0.9)* enables 興櫃 (TW emerging) — use it when you need pre-listing price action or revenue factors that don't exist in the main TSE/OTC catalog.

The rest of this file plus [dataframe-reference.md](dataframe-reference.md), [backtesting-reference.md](backtesting-reference.md), [best-practices.md](best-practices.md), [factor-analysis-reference.md](factor-analysis-reference.md), and [machine-learning-reference.md](machine-learning-reference.md) are **market-agnostic** — the APIs behave the same across markets.

For US-market work — whether single-name equities (`data.set_market('us')`) or ETFs/funds (`data.set_market('us_fund')`) — **read [us-market.md](us-market.md) first**. Queries that should trigger it include: US equity, S&P 500, NASDAQ 100, 美股, SPY / QQQ, sector SPDRs, leveraged / inverse ETFs, ETF rotation, `us_price:*`, `us_fund_price:*`, `data.us_universe(...)`, or `us_income_statement:*` / `us_cash_flow:*` / `us_balance_sheet:*`. It documents:

• Which US data tables are safe for backtesting versus current-snapshot-only (analyst consensus, ratios, DCF are live-only — do not use them historically)
• Filing-date-aligned quarterly fundamentals (`key_date == filing_date`) — no `.shift()` workaround needed
• `Report` API names on US (`creturn` / `daily_creturn` / `get_stats()`; no `get_equity()`)
• US backtest defaults for both markets: `USMarket` (`fee_ratio=0`, `tax_ratio=0`, `trade_at_price='close'`) and `USFundMarket` for ETF/fund backtests
• How `data.set_market(...)` is the session-scope switch (there is no `market=` kwarg on `data.get()`)
• Dollar-volume-top-N universe construction (works back to 2016), S&P 500 / NASDAQ 100 membership via `data.us_universe(index='S&P 500' | 'NASDAQ 100')` with its 2022-11 history-start caveat, quality gates, and sector-exclusion rationale
• Lookahead-bias checklist specific to US data (rolling-window universe filters, survivorship avoidance)
• ETF / sector-rotation backtesting via `USFundMarket` and `us_fund_price:*`

Other-market queries can skip that file.

API Token Tiers & Usage

Token Tiers

| Tier | Daily Limit | Token Pattern | | ---- | ----------- | ----------------- | | Free | 500 MB | ends with `#free` | | VIP | 5000 MB | no suffix |

Usage Reset

• Resets daily at **8:00 AM UTC+8**
• When limit exceeded, user must wait for reset or upgrade to VIP at [finlab.finance](https://finlab.finance)

Quick Start Example

from finlab import data
from finlab.backtest import sim

# 1. Fetch data
close = data.get("price:收盤價")
vol = data.get("price:成交股數")
pb = data.get("price_earning_ratio:股價淨值比")

# 2. Create conditions
cond1 = close.rise(10)  # Rising last 10 days
cond2 = vol.average(20) > 1000*1000  # High liquidity
cond3 = pb.rank(axis=1, pct=True) < 0.3  # Low P/B ratio

# 3. Combine conditions and select stocks
position = cond1 & cond2 & cond3
position = pb[position].is_smallest(10)  # Top 10 lowest P/B

# 4. Backtest
report = sim(position, resample="M", upload=False)

# 5. Print metrics - Two