# Taiwan Stock Institutional Trades (TWSE) - 三大法人買賣超 (`chamarix/twse-institutional-trades`) Actor Daily foreign/trust/dealer net buy-sell data for all 1,300+ Taiwan Stock Exchange (TWSE) listed stocks. Official T86 data feed, structured JSON, since 2012. - **URL**: https://apify.com/chamarix/twse-institutional-trades.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, NaN 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 a software tools running on the Apify platform, for all kinds of web data extraction and automation use cases. 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. In JavaScript/TypeScript projects, use official [JavaScript/TypeScript client](https://docs.apify.com/api/client/js.md): ```bash npm install apify-client ``` In Python projects, use official [Python client library](https://docs.apify.com/api/client/python.md): ```bash pip install apify-client ``` In shell scripts, use [Apify CLI](https://docs.apify.com/cli/docs.md): ````bash # MacOS / Linux curl -fsSL https://apify.com/install-cli.sh | bash # Windows irm https://apify.com/install-cli.ps1 | iex ```bash In AI frameworks, you might use the [Apify MCP server](https://docs.apify.com/platform/integrations/mcp.md). If your project is in a different language, use 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 Stock Institutional Trades (TWSE) Daily **foreign investor / investment trust / dealer buy-sell data** for all Taiwan Stock Exchange (TWSE) listed companies — straight from the official TWSE T86 data feed, normalized into clean JSON. Track the "smart money" flows that drive the Taiwan stock market. ### Why this data matters Taiwan's stock market is **institutionally driven**. Three institutional actor groups — foreign investors (外資), investment trusts (投信), and proprietary dealers (自營商) — collectively trade ~40-60% of daily volume. Their net buy/sell positions on TSMC (2330), Hon Hai (2317), MediaTek (2454), and 1,300+ other listed stocks are leading indicators watched by every serious Taiwan market participant. This Actor gives you that data programmatically — every trading day, back to 2012. ### Who this is for | Use case | User | |----------|------| | **Quantitative trading strategies** | Hedge funds, prop traders building factor models on Taiwan equities | | **Portfolio positioning** | Portfolio managers tracking foreign flows into semiconductors | | **Market research & publication** | Financial media, analysts writing on Asia markets | | **Academic finance research** | Asset pricing, market microstructure studies | | **Regulatory/policy analysis** | Tracking foreign capital flows during policy events | | **Retail investor tools** | Building apps that show institutional activity on specific stocks | ### What data you get For **every trading day** and **every listed stock**, the 19 fields: | Field | Chinese | Meaning | |-------|---------|---------| | `stock_code` | 證券代號 | Stock ticker (e.g., 2330) | | `stock_name` | 證券名稱 | Company name | | `foreign_buy` / `_sell` / `_net` | 外陸資 | Foreign investors (ex-dealer) | | `foreign_dealer_buy` / `_sell` / `_net` | 外資自營商 | Foreign proprietary dealers | | `trust_buy` / `_sell` / `_net` | 投信 | Investment trusts (domestic mutual funds) | | `dealer_prop_buy` / `_sell` / `_net` | 自營商(自行買賣) | Proprietary dealer (own account) | | `dealer_hedge_buy` / `_sell` / `_net` | 自營商(避險) | Proprietary dealer (hedging account) | | `dealer_net` | 自營商總計 | Dealer total net | | `total_institutional_net` | 三大法人買賣超 | **Combined institutional net position** | All quantities are in **shares** (not lots). ### Input parameters ```json { "startDate": "2026-04-01", "endDate": "2026-04-04", "stockCodes": ["2330", "2317", "2454"], "marketType": "TWSE" } ```` | Field | Type | Description | |-------|------|-------------| | `startDate` | string | YYYY-MM-DD (required) | | `endDate` | string | YYYY-MM-DD, inclusive. Empty = single day | | `stockCodes` | array | Filter to specific tickers. Empty = all ~1300 stocks | | `marketType` | enum | `TWSE` (listed). OTC/TPEx coming soon | ### Output example ```json { "date": "2026-04-01", "stock_code": "2330", "stock_name": "台積電", "foreign_buy": 12500000, "foreign_sell": 6318718, "foreign_net": 6181282, "foreign_dealer_net": 0, "trust_buy": 850000, "trust_sell": 120000, "trust_net": 730000, "dealer_prop_net": 1200000, "dealer_hedge_net": 1166171, "dealer_net": 2366171, "total_institutional_net": 9277453 } ``` A positive `total_institutional_net` means institutions bought more than they sold (bullish signal). ### Pricing **Pay-per-result**: $1.00 per 1,000 records. A full day of TWSE data (~1,300 stocks) = ~$1.30. Typical usage: - 1 day, specific 5 stocks: **~$0.005** - 1 month (20 trading days), all stocks: **~$26** - 1 year, specific 20 stocks: **~$0.25** ### Data availability - **Coverage**: All ~1,300 TWSE listed stocks + ETFs - **History**: From 2012-05-02 onwards - **Update frequency**: Daily at ~17:00 TPE time (after market close) - **Source**: [TWSE T86 official data feed](https://www.twse.com.tw/en/trading/fund/t86.html) ### Common quantitative use cases ```python ## 1. Find stocks with strongest foreign buying streaks ## Run for past 20 days, group by stock_code, sum foreign_net, rank desc ## 2. Detect institutional divergence ## Find stocks where foreign_net > 0 but trust_net < 0 ## 3. Cross-reference with price data ## Merge with TWSE daily quotes to compute foreign_flow × price correlation ## 4. Event-driven analysis ## Track institutional flows around earnings or macro events ``` ### Tips - For a **specific ticker**, always use `stockCodes` filter to minimize cost - For **time-series backfill**, run with a wide date range - TWSE skips weekends automatically — no wasted calls - Data is final at ~17:00 TPE daily — don't query same-day before that ### Disclaimer Data is sourced from TWSE's official public data feed. This Actor is not affiliated with or endorsed by Taiwan Stock Exchange. Accuracy depends on the source; verify critical trading decisions against official TWSE publications. ### Keywords Taiwan stock market data, TWSE API, foreign investor flows Taiwan, institutional trading Taiwan, TSMC institutional holdings, 三大法人, 外資買賣超, Taiwan quant trading data, Asia equities data, 投信持股, Taiwan financial data API, smart money Taiwan, 台股外資買賣超, Taiwanese market microstructure # Actor input Schema ## `startDate` (type: `string`): Start date in YYYY-MM-DD format. Data available from 2012-05-02 onwards. ## `endDate` (type: `string`): End date in YYYY-MM-DD format (inclusive). Leave empty to scrape only the start date. ## `stockCodes` (type: `array`): Optional list of stock codes to filter (e.g., \['2330', '2317']). Leave empty to get all stocks. ## `marketType` (type: `string`): TWSE (listed) or TPEx (OTC/櫃買). Currently only TWSE is supported. ## Actor input object example ```json { "startDate": "2026-04-01", "endDate": "", "stockCodes": [ "2330", "2317", "2454" ], "marketType": "TWSE" } ``` # 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 '' with your token const client = new ApifyClient({ token: '', }); // Prepare Actor input const input = { "startDate": "2026-04-01", "stockCodes": [ "2330", "2317", "2454" ] }; // Run the Actor and wait for it to finish const run = await client.actor("chamarix/twse-institutional-trades").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 '' with your token. client = ApifyClient("") # Prepare the Actor input run_input = { "startDate": "2026-04-01", "stockCodes": [ "2330", "2317", "2454", ], } # Run the Actor and wait for it to finish run = client.actor("chamarix/twse-institutional-trades").call(run_input=run_input) # Fetch and print Actor results from the run's dataset (if there are any) print("💾 Check your data here: https://console.apify.com/storage/datasets/" + run["defaultDatasetId"]) for item in client.dataset(run["defaultDatasetId"]).iterate_items(): print(item) # 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start ``` ## CLI example ```bash echo '{ "startDate": "2026-04-01", "stockCodes": [ "2330", "2317", "2454" ] }' | apify call chamarix/twse-institutional-trades --silent --output-dataset ``` ## MCP server setup ```json { "mcpServers": { "apify": { "command": "npx", "args": [ "mcp-remote", "https://mcp.apify.com/?tools=chamarix/twse-institutional-trades", "--header", "Authorization: Bearer " ] } } } ``` ## OpenAPI specification ```json { "openapi": "3.0.1", "info": { "title": "Taiwan Stock Institutional Trades (TWSE) - 三大法人買賣超", "description": "Daily foreign/trust/dealer net buy-sell data for all 1,300+ Taiwan Stock Exchange (TWSE) listed stocks. Official T86 data feed, structured JSON, since 2012.", "version": "0.1", "x-build-id": "KU2dZGbgJMbdIibuY" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/chamarix~twse-institutional-trades/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-chamarix-twse-institutional-trades", "x-openai-isConsequential": false, "summary": "Executes an Actor, waits for its completion, and returns Actor's dataset items in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK" } } } }, "/acts/chamarix~twse-institutional-trades/runs": { "post": { "operationId": "runs-sync-chamarix-twse-institutional-trades", "x-openai-isConsequential": false, "summary": "Executes an Actor and returns information about the initiated run in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/runsResponseSchema" } } } } } } }, "/acts/chamarix~twse-institutional-trades/run-sync": { "post": { "operationId": "run-sync-chamarix-twse-institutional-trades", "x-openai-isConsequential": false, "summary": "Executes an Actor, waits for completion, and returns the OUTPUT from Key-value store in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK" } } } } }, "components": { "schemas": { "inputSchema": { "type": "object", "required": [ "startDate" ], "properties": { "startDate": { "title": "Start date", "pattern": "^\\d{4}-\\d{2}-\\d{2}$", "type": "string", "description": "Start date in YYYY-MM-DD format. Data available from 2012-05-02 onwards.", "default": "2026-04-01" }, "endDate": { "title": "End date", "pattern": "^(|\\d{4}-\\d{2}-\\d{2})$", "type": "string", "description": "End date in YYYY-MM-DD format (inclusive). Leave empty to scrape only the start date.", "default": "" }, "stockCodes": { "title": "Stock codes filter", "type": "array", "description": "Optional list of stock codes to filter (e.g., ['2330', '2317']). Leave empty to get all stocks.", "default": [], "items": { "type": "string" } }, "marketType": { "title": "Market type", "enum": [ "TWSE" ], "type": "string", "description": "TWSE (listed) or TPEx (OTC/櫃買). Currently only TWSE is supported.", "default": "TWSE" } } }, "runsResponseSchema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "actId": { "type": "string" }, "userId": { "type": "string" }, "startedAt": { "type": "string", "format": "date-time", "example": "2025-01-08T00:00:00.000Z" }, "finishedAt": { "type": "string", "format": "date-time", "example": "2025-01-08T00:00:00.000Z" }, "status": { "type": "string", "example": "READY" }, "meta": { "type": "object", "properties": { "origin": { "type": "string", "example": "API" }, "userAgent": { "type": "string" } } }, "stats": { "type": "object", "properties": { "inputBodyLen": { "type": "integer", "example": 2000 }, "rebootCount": { "type": "integer", "example": 0 }, "restartCount": { "type": "integer", "example": 0 }, "resurrectCount": { "type": "integer", "example": 0 }, "computeUnits": { "type": "integer", "example": 0 } } }, "options": { "type": "object", "properties": { "build": { "type": "string", "example": "latest" }, "timeoutSecs": { "type": "integer", "example": 300 }, "memoryMbytes": { "type": "integer", "example": 1024 }, "diskMbytes": { "type": "integer", "example": 2048 } } }, "buildId": { "type": "string" }, "defaultKeyValueStoreId": { "type": "string" }, "defaultDatasetId": { "type": "string" }, "defaultRequestQueueId": { "type": "string" }, "buildNumber": { "type": "string", "example": "1.0.0" }, "containerUrl": { "type": "string" }, "usage": { "type": "object", "properties": { "ACTOR_COMPUTE_UNITS": { "type": "integer", "example": 0 }, "DATASET_READS": { "type": "integer", "example": 0 }, "DATASET_WRITES": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_READS": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_WRITES": { "type": "integer", "example": 1 }, "KEY_VALUE_STORE_LISTS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_READS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_WRITES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_INTERNAL_GBYTES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_EXTERNAL_GBYTES": { "type": "integer", "example": 0 }, "PROXY_RESIDENTIAL_TRANSFER_GBYTES": { "type": "integer", "example": 0 }, "PROXY_SERPS": { "type": "integer", "example": 0 } } }, "usageTotalUsd": { "type": "number", "example": 0.00005 }, "usageUsd": { "type": "object", "properties": { "ACTOR_COMPUTE_UNITS": { "type": "integer", "example": 0 }, "DATASET_READS": { "type": "integer", "example": 0 }, "DATASET_WRITES": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_READS": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_WRITES": { "type": "number", "example": 0.00005 }, "KEY_VALUE_STORE_LISTS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_READS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_WRITES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_INTERNAL_GBYTES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_EXTERNAL_GBYTES": { "type": "integer", "example": 0 }, "PROXY_RESIDENTIAL_TRANSFER_GBYTES": { "type": "integer", "example": 0 }, "PROXY_SERPS": { "type": "integer", "example": 0 } } } } } } } } } } ```