# Taiwan Block Trades API — 鉅額交易 (TWSE + TPEx) (`chamarix/taiwan-block-trades`) Actor

Every block trade printed on the Taiwan Stock Exchange and TPEx: price, share count, consideration, paired vs continuous, and the full constituent list behind each basket trade. TWSE history back to 2005, TPEx for the current year, cross-validated against each exchange's own statistics.

- **URL**: https://apify.com/chamarix/taiwan-block-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, 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 Block Trades API — 鉅額交易 (TWSE + TPEx)

Get structured JSON access to **every block trade printed on the Taiwan Stock Exchange and the Taipei Exchange** — price, share count, consideration, paired vs continuous, and the **full constituent list behind each basket trade**. TWSE history back to **2005-04-04**; TPEx for the current year.

A block trade is how a stake actually changes hands in Taiwan. A parent selling down, a life insurer rebalancing, a fund unwinding a position, an arbitrage desk crossing an ETF basket — none of it goes through the open order book, so none of it shows up in the daily quote. It prints in a separate report that this Actor turns into clean rows, then checks arithmetically against each exchange's own separately published statistics before emitting anything.

### Why this data matters

- **A single print can be a fifth of a day's turnover.** On 2026-08-13 the TWSE block-trade tape carried 47 trades worth **NT$10.7 billion**, of which one 台積電 (2330) cross alone was **2,780,000 shares at NT$2,435.00 — NT$6.77 billion**. That trade never touched the order book.
- **Basket trades come with their constituents.** TWSE files a 股票組合 trade as a single line with the securities hidden behind a drill-down. This Actor follows it. The basket printed on 2026-08-11 was **15 securities, 3,489,397 shares, NT$4.88 billion** — 台積電, 台達電, 聯發科, 緯穎, 大立光 and eleven more, each with its own price and size. That is an index-arbitrage or ETF-creation footprint you cannot see any other way.
- **Paired vs continuous tells you what kind of trade it was.** 配對交易 is a pre-negotiated cross between two counterparties who already agreed the price — read it as a stake transfer. 逐筆交易 was matched on the block-trade order book against whoever was there.
- **Twenty years of it.** TWSE has published this report since 2005-04-04, through three different column layouts, all of which this Actor reads.
- **Every number is checked, not just parsed.** Consideration must equal price × shares on each row; each day must reconcile with the report's own total; each basket must reconcile with its constituents; and the whole thing is compared against a *separate* official statistics publication on each exchange.

### Output

One record per block trade. Basket trades carry their constituents nested.

```json
{
  "date": "2026-08-13",
  "market": "TWSE",
  "record_type": "SINGLE_TRADE",
  "stock_code": "2330",
  "stock_name": "台積電",
  "trade_type": "PAIRED",
  "trade_type_zh": "配對交易",
  "trade_form": "SINGLE_SECURITY",
  "settlement_period": null,
  "price": 2435.0,
  "high_price": 2435.0,
  "low_price": 2435.0,
  "vwap_price": 2435.0,
  "shares": 2780000,
  "value": 6769300000,
  "trade_count": 1,
  "trading_time": null,
  "sequence_no": null,
  "reference_no": null,
  "component_count": null,
  "components": null,
  "value_matches_price_x_shares": true,
  "source": "TWSE_BFIAUU"
}
```

| Field | Meaning |
|---|---|
| `date` | 資料日期 — the trading day, `YYYY-MM-DD` |
| `market` | `TWSE` (listed 上市) or `TPEX` (OTC 上櫃) |
| `record_type` | `SINGLE_TRADE` (one executed trade), `BASKET_TRADE` (a TWSE 股票組合, constituents in `components`) or `DAILY_AGGREGATE` (TPEx's per-security daily line — see below) |
| `stock_code` / `stock_name` | 證券代號 / 證券名稱. Null on a basket, which spans several securities |
| `trade_type` / `trade_type_zh` | `PAIRED` (配對交易) or `CONTINUOUS` (逐筆交易); null before 2009, when TWSE did not print the distinction |
| `trade_form` | `SINGLE_SECURITY` (單一型) or `STOCK_BASKET` (組合型) |
| `settlement_period` | 交割期別 — `T+2日交割` or `T日交割`. TWSE printed it only from 2009 to 2011; TPEx prints it on every row |
| `price` | 成交價, NTD per share. Null where there is no single price |
| `high_price` / `low_price` / `vwap_price` | The day's range and 加權平均價 for that security and trade type. All three equal `price` on an individual trade |
| `shares` | 成交股數 — **shares, not the 1,000-share 張** that Taiwanese brokers quote |
| `value` | 成交金額 in whole New Taiwan dollars |
| `trade_count` | 成交筆數 — 1 on an individual or basket trade |
| `trading_time` | 成交時間, `HH:MM:SS`. TPEx publishes it on individual trades; TWSE does not publish it at all |
| `sequence_no` / `reference_no` | 序號 and the buy-side order reference TWSE files a basket under |
| `component_count` / `components` | 股票種數 and the securities inside a basket, each with its own price, shares and consideration |
| `value_matches_price_x_shares` | This Actor's own arithmetic check on the row |
| `source` | `TWSE_BFIAUU`, `TPEX_OPENAPI_TICKS` or `TPEX_OPENAPI_DAILY` |

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

1. **The two exchanges do not publish at the same granularity.** TWSE serves every individual trade for any day back to 2005. TPEx serves individual trades **for the current day only**; every other day of the current year comes as one row per security per trade type, which is why those rows say `DAILY_AGGREGATE` rather than pretending to be trades. Nothing before this January is available from TPEx at all.
2. **TWSE's 2005–2008 column headings are wrong.** That layout labels its last two columns 成交量 and 成交股數, but they actually hold the share count and the consideration — `price × column 4 == column 5` on every row confirms it. Read literally you would file a NT$56,902,000 trade as 56,902,000 shares. This Actor reads the layout by its identity, not its labels.
3. **TWSE's basket totals exclude nothing, but TPEx's daily rows include the baskets.** TWSE counts 單一證券 and 股票組合 separately — add them yourself for a market total. TPEx's daily feed is titled 單一證券 yet its monthly reconciliation only closes once the 組合型 line is added in, i.e. it lists basket constituents as ordinary per-security rows. Both behaviours are verified against each exchange's monthly statistics on every run.
4. **A few TPEx names have no security code.** The daily feed prints a name and no code. Names are resolved against the OTC equity list, which leaves convertible bonds and bond ETFs (`台灣大四`, `大聯大E1`, `中信ESG投資級債`) with a null `stock_code` rather than a wrong one.
5. **Most days have no block trades at all, and that is not an error.** 逐筆交易 in particular is rare — 24 trades in the whole of 2026 to date on TPEx. A day with an empty report returns no rows; a date the exchange refuses (a future date, or anything before 2005-04-04) is reported rather than silently substituted with the nearest day.

### Data source & reliability

- Straight from TWSE 鉅額交易日成交資訊 (`BFIAUU`, both 單一證券 and 股票組合 with the constituent drill-down) and TPEx's block-trade open-data feeds — the exchanges' own publications, no third-party intermediaries
- **Every row** must satisfy `value == price × shares` to the rounding the exchange publishes at, and every day must reconcile with the report's own 總計 line
- **Every basket** must reconcile with its constituents on share count, consideration and security count — exact, not approximate
- **Cross-checked against a second official publication.** TWSE's parsed volumes are compared with `BFIAUU_d`, the exchange's separately compiled daily statistics: 36 figures over the 9 days it covers reproduce exactly. On TPEx, the current day's individual trades are aggregated and compared with the daily feed, and the daily feed is summed by month and compared with the monthly statistics — all eight months of 2026 reconcile to the transaction, the share and the dollar
- Coverage starts 2005-04-04 on TWSE; earlier dates are refused by the exchange and the Actor clamps to that floor rather than emitting empty runs
- Three different TWSE column layouts (2005–2008, 2009–2011, 2012 onwards) are all read by column name, so a fourth will fail loudly instead of silently misfiling numbers

### Use cases

- **Stake-transfer detection** — screen for paired crosses above a threshold to catch a parent, a founder or a strategic holder moving a block before it appears in a filing
- **Index-arbitrage and ETF flow** — basket trades with their constituents are the visible footprint of creation/redemption and index rebalancing
- **Execution benchmarking** — compare a block print against that day's VWAP to see the discount or premium a size seller actually paid
- **Liquidity research** — measure what share of a stock's turnover never touches the order book, day by day, over twenty years
- **Event studies** — pull the days around an earnings shock or a placement and see who was crossing size into it

### 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-director-shareholdings](https://apify.com/chamarix/taiwan-director-shareholdings) — Monthly director/officer shareholdings & share-pledge ratio since 1999

**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

## `startDate` (type: `string`):

First trading day to cover, YYYY-MM-DD. Leave empty for the latest published trading day. TWSE has published block trades since 2005-04-04; TPEx's feed only carries the current year.

## `endDate` (type: `string`):

Last trading day to cover, inclusive. Leave empty to fetch only the start date. TWSE serves one request per day, so a long range is a long run — TPEx is fetched whole regardless of the range.

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

Which exchange to cover. Leave empty for both.

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

Optional list of security codes (e.g., \['2330', '2317']). A basket trade is kept when any security inside it matches. This filters what is emitted, not what is fetched — the range still costs the same.

## `tradeTypes` (type: `array`):

PAIRED (配對交易) is a pre-negotiated cross between two counterparties. CONTINUOUS (逐筆交易) is matched against the block-trade order book. Leave empty for both.

## `recordTypes` (type: `array`):

SINGLE\_TRADE is one executed trade. BASKET\_TRADE is one TWSE 股票組合 trade with its constituents nested. DAILY\_AGGREGATE is TPEx's per-security daily line, which is all TPEx publishes for days other than today. Leave empty for all.

## `minTradeValue` (type: `integer`):

Drop records worth less than this in New Taiwan dollars. Useful for isolating the handful of trades that actually move a stake, e.g. 1000000000 for a billion-dollar block.

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

Drop records below this many shares. Note the unit is shares, not the 1,000-share 張 that Taiwanese brokers quote.

## `includeBasketTrades` (type: `boolean`):

Fetch the 股票組合 report as well, and follow each basket's drill-down for its constituents. Costs one extra request per day plus one per basket; baskets are rare, so most days this is a single extra request.

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

Compare the parsed rows with each exchange's separately published block-trade statistics and log any disagreement. Two extra requests per run. Leave on unless you are optimising a very short run.

## `maxDays` (type: `integer`):

Safety stop on how many weekdays a single run will walk. Set 0 to lift it.

## Actor input object example

```json
{
  "startDate": "",
  "endDate": "",
  "markets": [
    "TWSE",
    "TPEX"
  ],
  "stockCodes": [],
  "tradeTypes": [],
  "recordTypes": [],
  "minTradeValue": 0,
  "minShares": 0,
  "includeBasketTrades": true,
  "crossCheck": true,
  "maxDays": 400
}
```

# Actor output Schema

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

One record per block trade — price, shares, consideration and trade type, with basket constituents nested.

# 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 = {
    "startDate": "",
    "endDate": "",
    "markets": [
        "TWSE",
        "TPEX"
    ],
    "stockCodes": [],
    "tradeTypes": [],
    "recordTypes": [],
    "minTradeValue": 0,
    "minShares": 0,
    "maxDays": 400
};

// Run the Actor and wait for it to finish
const run = await client.actor("chamarix/taiwan-block-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 '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = {
    "startDate": "",
    "endDate": "",
    "markets": [
        "TWSE",
        "TPEX",
    ],
    "stockCodes": [],
    "tradeTypes": [],
    "recordTypes": [],
    "minTradeValue": 0,
    "minShares": 0,
    "maxDays": 400,
}

# Run the Actor and wait for it to finish
run = client.actor("chamarix/taiwan-block-trades").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 '{
  "startDate": "",
  "endDate": "",
  "markets": [
    "TWSE",
    "TPEX"
  ],
  "stockCodes": [],
  "tradeTypes": [],
  "recordTypes": [],
  "minTradeValue": 0,
  "minShares": 0,
  "maxDays": 400
}' |
apify call chamarix/taiwan-block-trades --silent --output-dataset

```

## MCP server setup

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

```

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/AYdKjzpl37ieAWmer/builds/7ABBfghYo77gd4W0N/openapi.json