get_tw_insider_transfers

Taiwan insider share-transfer filings from TWSE (上市) and TPEx (上櫃), served from the local finbridge database.

⚠These are PRE-ANNOUNCEMENTS, not executed trades. Taiwan requires directors, supervisors, managers and 10% shareholders to declare a transfer BEFORE selling (內部人持股轉讓事前申報). There is no "sold" table at all — a declaration says what someone intends to transfer and by when. What does exist is the opposite: an 未轉讓 (not-transferred) table listing declarations whose window expired without a sale, with the filer's stated reason. This tool returns both.

This is why it is a separate tool from get_dart_insider_trades (Korea) and get_edgar_insider_trades (US Form 4), which report trades that already happened. Do not compare the numbers across those tools as if they were the same event.

⚠Coverage is short and has permanent holes. The upstream endpoints publish only the CURRENT day's table — there is no historical query — so our history starts when we began collecting and any day the collector missed is unrecoverable. The response's coverage.first_report_date and coverage.days say exactly how much history exists; "no rows" for an earlier date means we never had it, not that nobody filed.

⚠No rankings or aggregates in this version (no "most-sold-by-insiders this month"). A few days of snapshots is not a sample.

Units are SHARES (股) — not the thousands of shares used by Taiwan margin data. No monetary conversion is done: planned shares times a closing price is not a transaction value. Role, method and reason strings are returned in the original Chinese so they can be checked against the source.

Args:
- company: optional filter — TW 4-digit code, '2330.TW', 'tw:2330', or the company name
- from / to: report_date range (YYYY-MM-DD)
- role: substring of the declarant's role in Chinese (董事 / 監察人 / 經理人 / 大股東 / 法人董事代表人)
- min_shares: minimum planned_shares (applies to the transfer table only)
- include_untransferred: also return expired declarations that were not acted on (default true)
- limit: 1-200 (default 50); response_format: 'markdown' | 'json'

Returns: {market, company?, range, transfers: [{report_date, company, declarant_role, declarant_name, method, period_from, period_to, planned_shares, daily_max_shares, transferee, held, planned, after}], untransferred: [{report_date, company, declarant_role, declarant_name, untransferred, held, declared, reason}], coverage: {first_report_date, last_report_date, days}, notes, data_as_of, page_url}

Use when: someone asks what Taiwanese insiders have declared they intend to sell, or whether a declared sale actually went through (an 未轉讓 row means it did not). Don't use it to claim an insider "sold" — this data cannot show that.