# Taiwan Director Shareholdings & Pledge Ratio — 董監持股質押 (`chamarix/taiwan-director-shareholdings`) Actor

Monthly shareholding balances for every director, supervisor, officer and 10% holder of a Taiwan-listed company, with the share-pledge ratio that flags a stake financed by debt. Shares at election vs held now, related-party holdings, TWSE, TPEx and Emerging boards, back to 1999.

- **URL**: https://apify.com/chamarix/taiwan-director-shareholdings.md
- **Developed by:** [chris](https://apify.com/chamarix) (community)
- **Categories:** AI, Developer tools, Other
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $0.50 / 1,000 results

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.

Learn more: https://docs.apify.com/platform/actors/running/actors-in-store#pay-per-event

## What's an Apify Actor?

Actors are web data automations that power AI and operations. They run on the Apify platform to scrape websites, process data, connect APIs, and automate workflows.
In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours,
and optionally produces a well-defined JSON output, datasets with results, or files in key-value store.
In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server.
Actors are written with capital "A".

## How to integrate an Actor?

If asked about integration, you help developers integrate Actors into their projects.
You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready.
The best way to integrate Actors is as follows.

- **AI agents and MCP clients** — the [Apify MCP server](https://docs.apify.com/integrations/mcp.md) at `https://mcp.apify.com` (remote, streamable HTTP, OAuth on first use).
- **Agentic workflows and local Actor development** — [Agent Skills](https://apify.com/.well-known/agent-skills/index.json) with the [Apify CLI](https://docs.apify.com/cli/docs.md): `npm install -g apify-cli`, then `apify login`.
- **JavaScript/TypeScript projects** — the official [JS/TS client](https://docs.apify.com/api/client/js/docs.md): `npm install apify-client`.
- **Python projects** — the official [Python client](https://docs.apify.com/api/client/python/docs.md): `pip install apify-client`.
- **Any other language** — the [REST API](https://docs.apify.com/api/v2.md).

For usage examples, see the [API](#api) section below.

For more details, see Apify documentation as [Markdown index](https://docs.apify.com/llms.txt) and [Markdown full-text](https://docs.apify.com/llms-full.txt).

# README

## Taiwan Director & Officer Shareholdings + Share Pledge Ratio (TWSE + TPEx)

Get structured JSON access to the **monthly shareholding balance of every director, supervisor, officer and 10% shareholder of every company that files with Taiwan's Market Observation Post System** — including the **share-pledge ratio**, the single most watched governance red flag in the Taiwanese market. Listed, OTC and emerging boards, with history back to **1999**.

Taiwan requires every insider to disclose, every month, how many shares they hold, how many of those are pledged as loan collateral, and how many sit with their spouse, minor children or a nominee. The exchanges' open-data feeds carry only the latest month. This Actor serves that month for the whole market in one request per board, reads any older month straight out of MOPS, and verifies every published pledge ratio arithmetically before emitting a row.

### Why this data matters

- **Pledged shares are borrowed money against a stake.** A chairman who has pledged 98% of their holding has financed it with debt and cannot ride out a drawdown — a falling price triggers a margin call, and the forced sale of a control block drags the price further. On 2026-06, **225 published TWSE rows held over a million shares with at least 80% of them pledged**, including 佳峻投資, chairman of 華建 (2530), with 264,150,000 of 267,222,599 shares pledged.
- **Insider accumulation, measured against the day they took office.** Every row carries both `shares_at_election` and `shares_held`, so you can see who has bought since being elected and who has been quietly selling down, without reconstructing it from transaction filings.
- **The household, not just the individual.** `related_party_shares` is the block held by the insider's spouse, minor children and nominees — disclosed precisely because it sits under the same control. It is often larger than the insider's own line.
- **Real history, not an accumulating snapshot.** MOPS answers for any month back to **1999-01**, so you can chart a control block's pledge ratio through the 2008 crisis or watch a founder's stake decay over twenty years.
- **All three boards.** 1,080 TWSE, 891 TPEx and 354 emerging-board companies filed for 2026-06 — **51,646 insider rows** in a single run.

### Output

One record per insider, per office held, per month.

```json
{
  "data_month": "2026-06",
  "report_date": "2026-07-20",
  "market": "TWSE",
  "stock_code": "2330",
  "company_name": "台積電",
  "title": "董事長本人",
  "role_category": "DIRECTOR",
  "is_juridical_representative": false,
  "holder_name": "魏哲家",
  "shares_at_election": 6392834,
  "shares_held": 7452349,
  "pledged_shares": 1600000,
  "pledged_ratio_pct": 21.46,
  "implied_trust_shares": null,
  "pledge_ratio_uses_trust_denominator": false,
  "related_party_shares": 700261,
  "related_party_pledged_shares": 0,
  "related_party_pledged_ratio_pct": 0,
  "household_shares": 8152610,
  "household_pledged_shares": 1600000,
  "source": "OPENAPI"
}
```

| Field | Meaning |
|---|---|
| `data_month` | The month the balance is stated as of, `YYYY-MM` |
| `report_date` | 出表日期 — when the compiled report was published, about the 20th of the following month. `null` on rows read from MOPS, which does not print it |
| `market` | `TWSE`, `TPEX` or `EMERGING` |
| `title` / `role_category` | 職稱 verbatim, plus a normalized category: `DIRECTOR`, `INDEPENDENT_DIRECTOR`, `SUPERVISOR`, `INDEPENDENT_SUPERVISOR`, `MANAGER`, `MAJOR_SHAREHOLDER`, `OTHER` |
| `is_juridical_representative` | True when the title ends 之法人代表人 — the person occupying a corporate holder's board seat |
| `shares_at_election` / `shares_held` | 選任時持股 and 目前持股. Both exclude preferred shares and discretionary-retention trust shares |
| `pledged_shares` / `pledged_ratio_pct` | 設質股數 and the ratio exactly as published |
| `implied_trust_shares` | Trust shares recovered from the ratio — see below. Not a published column |
| `related_party_*` | The spouse / minor children / nominee block, its pledged portion and ratio |
| `household_*` | Insider plus related party, computed here |
| `source` | `OPENAPI` (whole board, latest month) or `MOPS` (one company-month, any month back to 1999) |

#### Four things about this report that will bite you

**1. One person can appear several times, with the same shares each time.** MOPS states it outright: 內部人若具二種以上身份，每種身份別會揭露同樣股數，勿重複累計 — an insider holding two offices is published once per office, repeating the identical holding. 魏哲家 appears at 台積電 (2330) as both 董事長本人 and 總經理本人 with 7,452,349 shares on both rows. On 2026-06, **3,469 of 22,508 company-person pairs on the TWSE board were published more than once**. Summing `shares_held` over a company therefore double-counts. Deduplicate on `(stock_code, holder_name)` first, or filter to a single `role_category`.

**2. A representative's row is not the corporate seat's holding.** A corporate shareholder sitting on a board is published twice: 董事本人 carries the company's own stake, and 董事之法人代表人 carries the personal holding of the individual who occupies the seat — usually zero. Use `is_juridical_representative` to tell them apart; treating a representative's row as the block's size understates it to nothing. One corporate shareholder can also hold several seats, and then its identical holding is published once per seat, each paired with a different representative — 台灣鋼鐵 appears twice at 精剛 (1584) with 20,000,000 shares on both rows, for 林輝政's seat and 顏慶利's. That is the source data, not a duplicate.

**3. The pledge ratio has a denominator you cannot see.** Note 2 of the report defines it as pledged ÷ (currently held **+ shares under a discretionary-retention trust**), and the trust leg is not a column anywhere on the page. Most of the time it is zero and the ratio is just pledged ÷ held. When it is not, the published ratio comes out *lower* than pledged ÷ held would suggest — 李瑞勳 at 廣隆 (1537) shows 1,100,000 pledged against 4,751,802 held, which is 23.15%, but the report prints 19.20%. This Actor recovers the hidden balance and puts it in `implied_trust_shares`, flagging the row with `pledge_ratio_uses_trust_denominator`. Across all 51,646 rows of 2026-06 that was 46 of the 2,280 pledged rows.

**4. The published ratio is truncated, not rounded.** 21.4699% is printed as `21.46`, not `21.47`. Verified against all 51,646 rows — do not expect a recomputed ratio to match to the last decimal unless you truncate too.

### Data integrity

Two independent publications carry this report, and this Actor checks itself against both.

**Every pledge ratio is reproduced arithmetically, on every run.** For each pledged row the published ratio must equal either `floor(pledged ÷ held)` to two decimals, or the same expression with a positive trust balance in the denominator. Across the three boards for 2026-06 — **51,646 rows, 2,280 of them pledged — every single one reproduced**: 2,234 exactly, 46 via a recovered trust balance, none left unexplained. Anything that fails is named in the log rather than published quietly.

**The open-data feed is cross-checked against MOPS' own report.** The TWSE and TPEx feeds (`t187ap11_L`, `mopsfin_t187ap11_O`, `mopsfin_t187ap11_R`) and the MOPS 董監事持股餘額明細 report are separate renderings of the same filings, reached through completely different query paths. Comparing them company by company for 2026-06 — 台泥 (52 insiders), 台積電 (43), 鴻海 (20), 玉山金 (57) — gave **172 rows with zero differences on any of the seven numeric columns**. The check runs on every execution (`crossCheck`, on by default) over the first three companies of each board, so a change in either publication shows up as a warning in the log.

Beyond that, the parser refuses to guess. The MOPS table header is verified cell by cell before a single row is read, and the month MOPS echoes back must match the month requested — a report served for the wrong month fails the run rather than filing one month's balances under another. An unknown security code, a month before the archive begins and a month that has not happened yet all return no rows and no error, because MOPS answers all three with the same empty page.

### Input

| Field | Type | Description |
|---|---|---|
| `startMonth` | string | `YYYY-MM`. **Leave empty for the latest published month** — the fast path, whole market, one request per board. History goes back to `1999-01` |
| `endMonth` | string | `YYYY-MM` inclusive; empty = just the start month |
| `markets` | array | Any of `TWSE`, `TPEX`, `EMERGING`. Empty = all three |
| `stockCodes` | array | e.g. `["2330", "2454"]`. Empty = every company. Essential for historical months |
| `roleCategories` | array | Filter by office category. Empty = all |
| `pledgedOnly` | boolean | Drop rows with no pledged shares |
| `minPledgeRatio` | integer | Keep only rows at or above this published pledge ratio |
| `minShares` | integer | Keep only rows holding at least this many shares |
| `maxCompaniesPerMonth` | integer | Cap on companies fetched for a historical month without `stockCodes`. Default 100, `0` = no cap. Anything dropped is named in the log |
| `crossCheck` | boolean | Read three companies back off MOPS and log whether the feed reproduces. Default `true` |

Example — the whole market, latest month:

```json
{}
```

Example — a pledge-risk screen across the listed and OTC boards:

```json
{
  "markets": ["TWSE", "TPEX"],
  "pledgedOnly": true,
  "minPledgeRatio": 70,
  "minShares": 1000000
}
```

Example — six years of one founder's stake and its pledge ratio:

```json
{
  "startMonth": "2020-01",
  "endMonth": "2026-06",
  "stockCodes": ["2330"],
  "roleCategories": ["DIRECTOR"]
}
```

### Pricing & cost control

Pay per result: **$0.50 / 1,000 records**.

- Whole market, latest month: 51,646 records ≈ $25.82 (TWSE 27,451 + TPEx 17,499 + emerging 6,696, measured on 2026-06)
- TWSE only, latest month: 27,451 records ≈ $13.73
- A pledge-risk screen (`pledgedOnly` + `minPledgeRatio: 70`) across TWSE + TPEx: a few hundred records ≈ $0.15
- Six years of monthly history for one ticker's directors: ~450 records ≈ $0.23

Filters are applied before anything is written, so `pledgedOnly`, `minPledgeRatio`, `minShares`, `roleCategories` and `stockCodes` all cut the bill directly — a full-market screen for leveraged insiders costs a fraction of the full board dump. Historical months are the slow path, not the expensive one: MOPS serves one company-month per request, so 10 tickers over 12 months is 120 requests but only a few hundred records.

### Data source & reliability

- Latest month direct from the TWSE and TPEx open-data feeds (`t187ap11_L`, `mopsfin_t187ap11_O`, `mopsfin_t187ap11_R`); any other month direct from MOPS 董監事持股餘額明細 (`ajax_stapap1`) — the exchanges' own publications, no third-party intermediaries
- Coverage starts at 1999-01; earlier months return the same empty page for every company, and the Actor clamps requests up to that floor rather than emitting empty runs
- The report is compiled monthly and published around the 20th of the following month. MOPS is typically a month ahead of the open-data feed, so a month the feed does not yet carry is fetched from MOPS automatically
- 公開發行 (registered but not traded) companies are out of scope — they are published in a layout without a security code
- Titles are read by longest keyword match, so 獨立董事 is never collapsed into 董事 and 副總經理 is never read as 經理. A title MOPS has not used before lands in `OTHER` rather than failing the run — the roster of offices is the filing company's to write

### Use cases

- **Governance screening** — rank a portfolio by insider pledge ratio and flag control blocks financed with debt before a drawdown forces them out
- **Insider conviction** — compare `shares_held` against `shares_at_election` across a board to see who has been buying since taking office
- **Event studies** — pull the month before and after a proxy fight, a placement or a resignation and diff the entire insider roster
- **Ownership mapping** — trace which corporate entities hold board seats and who represents them, across a whole market in one run
- **Backtesting** — build a monthly pledge-ratio factor going back two decades and test it against forward returns

### Taiwan Market Data Suite

This Actor is part of a suite of 19 Taiwan market data APIs by [chamarix](https://apify.com/chamarix) — official sources only, cross-validated against independent official endpoints, clean JSON out. Code samples for the whole suite: [GitHub](https://github.com/cc77556/taiwan-market-data-actors).

**Market data:**

- [twse-institutional-trades](https://apify.com/chamarix/twse-institutional-trades) — Daily institutional buy/sell (foreign, investment trust, dealer) per stock — TWSE listed
- [tpex-institutional-trades](https://apify.com/chamarix/tpex-institutional-trades) — Daily institutional buy/sell per stock — TPEx OTC market
- [taiwan-monthly-revenue](https://apify.com/chamarix/taiwan-monthly-revenue) — Monthly revenue of 1,900+ listed & OTC companies, MoM/YoY
- [taiwan-financial-statements](https://apify.com/chamarix/taiwan-financial-statements) — Quarterly income statement, balance sheet & cash flow back to 2013
- [taiwan-dividend-calendar](https://apify.com/chamarix/taiwan-dividend-calendar) — Ex-dividend / ex-rights dates, reference prices & payouts back to 2003
- [taiwan-shareholder-meetings](https://apify.com/chamarix/taiwan-shareholder-meetings) — Shareholder meeting dates, book closure periods, board elections & e-voting since 2005
- [taiwan-emerging-stock-quotes](https://apify.com/chamarix/taiwan-emerging-stock-quotes) — Emerging Stock Board (興櫃) quotes, pre-IPO company register & listing-application status
- [taiwan-margin-trading](https://apify.com/chamarix/taiwan-margin-trading) — Daily margin trading & short sale balances per stock
- [taiwan-sbl-short-sale-balance](https://apify.com/chamarix/taiwan-sbl-short-sale-balance) — Securities-lending short sale balances per stock
- [taiwan-day-trading-stats](https://apify.com/chamarix/taiwan-day-trading-stats) — Day-trading volume, value & ratio per stock since 2014
- [tdcc-shareholding-dispersion](https://apify.com/chamarix/tdcc-shareholding-dispersion) — Weekly TDCC shareholding dispersion (retail vs whale structure)
- [taiwan-foreign-shareholding](https://apify.com/chamarix/taiwan-foreign-shareholding) — Foreign ownership percentage & remaining quota per stock
- [taifex-institutional-derivatives](https://apify.com/chamarix/taifex-institutional-derivatives) — Institutional futures & options positions (TAIFEX), incl. put/call ratio
- [taiwan-stock-alerts](https://apify.com/chamarix/taiwan-stock-alerts) — Watch-list, disposition & short-sale suspension alerts
- [taiwan-insider-share-transfers](https://apify.com/chamarix/taiwan-insider-share-transfers) — Insider share-transfer filings (directors, officers, 10% holders) since 2002
- [taiwan-block-trades](https://apify.com/chamarix/taiwan-block-trades) — Every block trade (鉅額交易) with price, size & basket constituents since 2005

**Government & civic data:**

- [taiwan-legislator-monitor](https://apify.com/chamarix/taiwan-legislator-monitor) — Legislative Yuan bills, legislators & meetings
- [taiwan-tender-monitor](https://apify.com/chamarix/taiwan-tender-monitor) — Government e-procurement tenders (open calls, awards, failures)

# Actor input Schema

## `startMonth` (type: `string`):

Month of the shareholding balance in YYYY-MM format. Leave empty for the latest published month, which is what the open-data feed carries — that is the fast path and covers every listed company in one request per board. MOPS holds this report from 1999-01 onwards.

## `endMonth` (type: `string`):

Last month to cover, inclusive. Leave empty to fetch only the start month. Any month the open-data feed does not carry is read off MOPS one company at a time, so a historical range is far slower — set stockCodes to keep it sane.

## `markets` (type: `array`):

Which boards to cover. Leave empty for all three. 公開發行 (registered but untraded) companies are not covered.

## `stockCodes` (type: `array`):

Optional list of security codes (e.g., \['2330', '2454']). On the latest month this just filters the feed. On a historical month it is what makes the run affordable — MOPS serves one company-month per request, so listing 10 codes over 12 months is 120 requests.

## `roleCategories` (type: `array`):

Keep only insiders holding one of these offices. Derived from the 職稱 string MOPS publishes, longest match first, so 獨立董事 is never read as 董事. Leave empty for all.

## `pledgedOnly` (type: `boolean`):

Drop every row whose 設質股數 is zero. Pledging is how an insider raises cash against a stake without selling it, so this narrows the board straight to the leveraged holders.

## `minPledgeRatio` (type: `integer`):

Keep only rows whose published 設質股數佔持股比例 is at least this. A high ratio on a controlling holder is the classic Taiwanese warning sign — the stake is collateral, and a falling price can force it to be sold. Leave at 0 for everything.

## `minShares` (type: `integer`):

Keep only rows where 目前持股 is at least this many shares. Useful for cutting the long tail of officers holding nothing. Leave at 0 for everything.

## `maxCompaniesPerMonth` (type: `integer`):

Safety valve for a historical month requested without stockCodes: MOPS would otherwise be asked for every one of the ~1,080 listed companies, one request each. 0 means no cap. Whatever is dropped is named in the log — nothing is silently truncated.

## `crossCheck` (type: `boolean`):

For a month taken from the open-data feed, read the first three companies back off MOPS' own report — an entirely separate query path — and log whether every value reproduces. Costs three extra requests per board and never changes the output.

## Actor input object example

```json
{
  "startMonth": "",
  "endMonth": "",
  "markets": [
    "TWSE",
    "TPEX"
  ],
  "stockCodes": [],
  "roleCategories": [],
  "pledgedOnly": false,
  "minPledgeRatio": 0,
  "minShares": 0,
  "maxCompaniesPerMonth": 100,
  "crossCheck": true
}
```

# Actor output Schema

## `datasetItems` (type: `string`):

One record per insider, per office held, per month — holdings, pledged shares and pledge ratio.

# API

You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup.

## JavaScript example

```javascript
import { ApifyClient } from 'apify-client';

// Initialize the ApifyClient with your Apify API token
// Replace the '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {
    "startMonth": "",
    "endMonth": "",
    "markets": [
        "TWSE",
        "TPEX"
    ],
    "stockCodes": [],
    "roleCategories": [],
    "minPledgeRatio": 0,
    "minShares": 0,
    "maxCompaniesPerMonth": 100
};

// Run the Actor and wait for it to finish
const run = await client.actor("chamarix/taiwan-director-shareholdings").call(input);

// Fetch and print Actor results from the run's dataset (if any)
console.log('Results from dataset');
console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`);
const { items } = await client.dataset(run.defaultDatasetId).listItems();
items.forEach((item) => {
    console.dir(item);
});

// 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs

```

## Python example

```python
from apify_client import ApifyClient

# Initialize the ApifyClient with your Apify API token
# Replace '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = {
    "startMonth": "",
    "endMonth": "",
    "markets": [
        "TWSE",
        "TPEX",
    ],
    "stockCodes": [],
    "roleCategories": [],
    "minPledgeRatio": 0,
    "minShares": 0,
    "maxCompaniesPerMonth": 100,
}

# Run the Actor and wait for it to finish
run = client.actor("chamarix/taiwan-director-shareholdings").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print(f"💾 Check your data here: https://console.apify.com/storage/datasets/{run.default_dataset_id}")
for item in client.dataset(run.default_dataset_id).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{
  "startMonth": "",
  "endMonth": "",
  "markets": [
    "TWSE",
    "TPEX"
  ],
  "stockCodes": [],
  "roleCategories": [],
  "minPledgeRatio": 0,
  "minShares": 0,
  "maxCompaniesPerMonth": 100
}' |
apify call chamarix/taiwan-director-shareholdings --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,chamarix/taiwan-director-shareholdings"
        }
    }
}

```

The hosted server signs you in with OAuth on first connect, so no API token belongs in this config. Clients without OAuth support can send an `Authorization: Bearer <APIFY_API_TOKEN>` header instead, using a token from API & Integrations in Apify Console (https://console.apify.com/settings/integrations).

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/QCVOtoqoQBwRRuDKI/builds/Gvb5FfV21cchc2O7K/openapi.json