# Tw Stock Data

> Fetch, validate, and analyze Taiwan stock, OTC, futures, options, and MOPS financial datasets using the tw-stock CLI. Use whenever the user asks for TWSE, TPEX, TAIFEX, MOPS, 台股, 上市櫃, 期貨, 選擇權, 法人買賣超, 融資融券, 外資持股, 股價, 月營收, 財報, or Taiwan market data, even if they do not mention the CLI.

- Skill: `lloyd3126/tw-stock-data` (Agent Skill, multi-file: 6 files)
- Install (CLI): `npx skillmds@latest add lloyd3126/tw-stock-data`
- Raw SKILL.md: https://api.skillmd.com/api/skills/lloyd3126/tw-stock-data/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: lloyd3126 (https://skillmd.com/u/lloyd3126)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/lloyd3126/tw-stock-data

---


# Taiwan Stock Data

Use this skill to help users discover, fetch, validate, and analyze Taiwan market datasets exposed by the `tw-stock` CLI.

The CLI is the source of truth. Prefer calling `tw-stock` or `uv run tw-stock` instead of reimplementing crawler logic in the agent.

The current CLI normalizes common output columns to English `snake_case`. Before writing analysis code that depends on exact columns, inspect `tw-stock describe <dataset> --json`, `tw-stock fetch <dataset> --schema-only --format json`, or [references/datasets.md](references/datasets.md).

## Dependency

This skill does not bundle the market data crawler itself. It expects the `tw-stock` CLI from the `tw-stock-cli` project to be available.

Use commands in this order:

1. If `tw-stock` is installed in the current environment, call `tw-stock ...`.
2. If working inside a checkout of the `tw-stock-cli` project, call `uv run tw-stock ...` from that repository root, or use `uv run --project /path/to/tw-stock-cli tw-stock ...` when running from another directory.
3. If neither command is available, tell the user that the skill can identify the right dataset and command, but fetching requires installing or opening the `tw-stock-cli` project.

## First steps

1. If the user is asking what data exists, run:

   ```bash
   tw-stock list-datasets --json
   ```

2. If the user mentions a specific topic but not a dataset ID, inspect [the dataset catalog](references/datasets.md) and map their request to the closest dataset.

3. Before fetching a large dataset, describe it or sample it:

   ```bash
   tw-stock describe taifex.futures-tick --json
   tw-stock fetch taifex.futures-tick --date 2026-04-30 --limit 5 --format json
   ```

4. For analysis workflows, prefer `jsonl` for AI/tool pipelines and `csv` for user-facing files:

   ```bash
   tw-stock fetch twse.stock-price --date 2026-04-30 --format jsonl
   tw-stock fetch twse.stock-price --date 2026-04-30 --format csv --output data.csv
   ```

5. Use metadata-only flags before fetching when the user needs schema or source context:

   ```bash
   tw-stock fetch twse.stock-price --schema-only --format json
   tw-stock fetch twse.stock-price --source-url-only --format json
   ```

## Dataset selection

Use these common mappings:

- Stock price / open-high-low-close: `twse.stock-price`, `tpex.stock-price`
- Stock list / security codes: `twse.stock-list`, `tpex.stock-list`
- PER / dividend yield / PBR: `twse.stock-per`, `tpex.stock-per`
- Institutional investor buy/sell: `twse.institutional-trade`, `tpex.institutional-trade`
- Margin purchase / short sale: `twse.margin-trade`, `tpex.margin-trade`
- Foreign holdings: `twse.foreign-holding`, `tpex.foreign-holding`
- Total return indices: `twse.total-return-index`, `tpex.total-return-index`
- Futures and options market data: `taifex.*`
- Monthly revenue and financial statements: `mops.month-revenue`, `mops.company-*`, `mops.income-statement`, `mops.balance-sheet`, `mops.cash-flow`
- MOPS PDF/electronic-book download indexes: `mops.financial-report-electronic-book`, `mops.annual-report-electronic-book`, `mops.related-company-reports`, `mops.sustainability-report`, `mops.major-shareholder-relationship`
- MOPS governance, ESG, insiders, related-party, and corporate actions: inspect [references/datasets.md](references/datasets.md) and prefer the exact `mops.*` dataset before scraping MOPS manually.

For the complete list, read [references/datasets.md](references/datasets.md).

## Column expectations

Use normalized column names from the current CLI:

- Price columns are `open`, `high`, `low`, `close`; do not assume old names such as `max` or `min`.
- Valuation columns are `per` and `pbr`; do not assume old uppercase names such as `PER` or `PBR`.
- Security identifiers are `stock_id` and `stock_name`.
- TAIFEX FCM outputs use `fcm_id`, `fcm_name`, `subtotal`, `total`, `market_share`, product columns such as `mtx`, and total product columns such as `total_mtx`.
- MOPS statement line items may remain in Chinese, but shared identifier columns are normalized to `stock_id` and `stock_name`.

## Safety and data quality

Taiwan exchange endpoints can change format. If the user needs reliable output, validate first:

```bash
tw-stock validate twse.stock-price --date 2026-04-30 --json
```

If validation fails, report the dataset ID, date/parameters, error code, and source URL. Do not silently substitute another data source unless the user asks for that.

For non-trading days, expect empty data or exchange messages. Ask for a nearby trading day only if the user's date is ambiguous.

## Large datasets

Tick data can return hundreds of thousands of rows. Always use `--limit` when exploring:

```bash
tw-stock fetch taifex.options-tick --date 2026-04-30 --limit 20 --format jsonl
```

Only fetch full tick datasets when the user clearly needs full raw data or provides an output path.

## Reference files

- [references/datasets.md](references/datasets.md): dataset IDs, parameters, and examples.
- [references/cli-usage.md](references/cli-usage.md): command patterns and output formats.
- [references/data-caveats.md](references/data-caveats.md): known source quirks and edge cases.