# TAIFEX Institutional Traders — Taiwan Futures & Options (`chamarix/taifex-institutional-derivatives`) Actor

Daily dealer, investment trust and foreign institutional positions across all 23 TAIFEX futures and 5 options contracts: long/short volume, net flow and open interest, plus the TAIEX options put/call ratio. Official Taiwan Futures Exchange data for positioning analysis and quant research.

- **URL**: https://apify.com/chamarix/taifex-institutional-derivatives.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

## TAIFEX Institutional Traders — Taiwan Futures & Options Positions

Get structured JSON access to **what Taiwan's three institutional trader groups do in the derivatives market every day** — across all 23 TAIFEX futures contracts and all 5 options contracts, with both daily flow and end-of-day open interest.

The Taiwan Futures Exchange publishes 三大法人 (three major institutional investors) positioning after every session:

- **外資及陸資 (foreign & mainland investors)** — the dominant force in TAIEX futures; their net open interest is the single most-watched positioning number in Taiwan markets
- **投信 (investment trusts)** — domestic funds, mostly hedging equity books
- **自營商 (dealers)** — proprietary desks and market makers, typically the fastest-turning of the three

Spot institutional flow tells you what they bought today. **Futures open interest tells you how they are positioned for tomorrow** — and unlike the cash market, it shows direction and leverage.

### Why this data matters

- **Foreign net OI in TAIEX futures (TXF)** is the standard proxy for offshore positioning on Taiwan; large swings routinely precede index moves
- **Open interest, not just flow** — a desk can be a net seller today while still holding a large net long; only the OI columns show the standing bet
- **Put/call ratio** on TAIEX options (optional output) is the classic contrarian sentiment gauge; the OI-based ratio is the version Taiwan desks actually quote
- **Calls and puts split separately** for options, so you can see whether a group is buying upside or paying for protection
- Micro and mini contracts (`TMF`, `MXF`) reveal retail-adjacent flow that the large contract hides
- 22 non-index futures — semiconductors, shipping, biotech, plus overseas indices (S\&P 500, Nasdaq-100, TOPIX, FTSE 100) — are covered by the same schema

### Output

One record per contract, per institution, per trading day. Futures produce 69 rows/day (23 contracts × 3 institutions); options produce 30 rows/day (5 contracts × call/put × 3 institutions).

```json
{
  "record_type": "INSTITUTIONAL_POSITION",
  "date": "2026-07-30",
  "contract_code": "TXF",
  "contract_name": "臺股期貨",
  "contract_name_en": "TAIEX Futures",
  "contract_type": "FUTURES",
  "call_put": null,
  "institution": "DEALER",
  "institution_zh": "自營商",
  "is_overseas_index": false,
  "buy_volume": 8948,
  "buy_value_thousands": 72462872,
  "sell_volume": 9565,
  "sell_value_thousands": 77393618,
  "net_volume": -617,
  "net_value_thousands": -4930746,
  "buy_open_interest": 6991,
  "buy_open_interest_value_thousands": 56441635,
  "sell_open_interest": 4995,
  "sell_open_interest_value_thousands": 40306880,
  "net_open_interest": 1996,
  "net_open_interest_value_thousands": 16134755,
  "market_direction_net_volume": -617,
  "market_direction_net_open_interest": 1996
}
```

| Field | Meaning |
|---|---|
| `contract_code` | Official TAIFEX product code (`TXF`, `MXF`, `TXO`, …) |
| `contract_type` / `call_put` | `FUTURES` or `OPTIONS`; `CALL`/`PUT` on options rows, `null` on futures |
| `institution` | `DEALER` (自營商), `INVESTMENT_TRUST` (投信), `FOREIGN` (外資及陸資) |
| `is_overseas_index` | `true` for the six foreign-index futures — see the note below |
| `buy_volume` / `sell_volume` | Contracts bought / sold during the session (futures 多方/空方交易口數, options 買方/賣方交易口數) |
| `net_volume` | Daily flow: contracts bought minus sold |
| `buy_open_interest` / `sell_open_interest` | Contracts held at the close on each side |
| `net_open_interest` | **Net standing position** — the headline positioning number |
| `market_direction_net_volume` / `market_direction_net_open_interest` | Bullish-positive versions of the two net fields — see the note below |
| `*_value_thousands` | Matching notional values in NT$ thousands |

With `includePutCallRatio` enabled, one extra row per trading day carries `record_type: "PUT_CALL_RATIO"` with `put_volume`, `call_volume`, `put_call_volume_ratio_pct`, `put_open_interest`, `call_open_interest` and `put_call_oi_ratio_pct` for TAIEX options.

#### Reading options rows correctly

The exchange labels the futures columns 多方/空方 (long/short) but the options columns 買方/賣方 (buy-side/sell-side). Both literally mean bought and sold — which is why this Actor names them `buy_*` and `sell_*` — but **on a put, the buyer is short the market**. Treating `buy_open_interest` on a put row as a long position silently inverts the signal.

Use `market_direction_net_volume` and `market_direction_net_open_interest` when you want a directional read: they equal the plain net fields for futures and calls, and flip sign for puts. Summed across contracts, they reproduce TAIFEX's own aggregate long/short totals exactly.

Two things to know if you want to reproduce the exchange's published headline numbers:

- TAIFEX **excludes the six overseas-index futures** (`TJF`, `SPF`, `UNF`, `UDF`, `SXF`, `F1F`) from its aggregate table — filter on `is_overseas_index: false`
- Options totals are stated in market direction, so use the `market_direction_*` fields

Both rules were derived by reconciling this Actor's output against the official aggregate feed, not assumed.

#### Contracts covered

**Futures (23):** `TXF` TAIEX · `MXF` Mini-TAIEX · `TMF` Micro-TAIEX · `EXF` Electronics · `FXF` Finance · `ZEF` Mini Electronics · `ZFF` Mini Finance · `STF` Single Stock · `ETF` ETF · `GTF` TPEx Index · `XIF` Non-Finance Non-Electronics · `G2F` TPEx 200 · `M1F` Taiwan Mid-Cap 100 · `E4F` Taiwan Sustainability · `BTF` Taiwan Biotech · `SOF` Semiconductor 30 · `SHF` Shipping · `TJF` TOPIX · `SPF` S\&P 500 · `UNF` Nasdaq-100 · `UDF` Dow Jones · `SXF` PHLX Semiconductor · `F1F` FTSE 100

**Options (5):** `TXO` TAIEX · `TEO` Electronics · `TFO` Finance · `STO` Single Stock · `ETC` ETF

### Input

| Field | Type | Description |
|---|---|---|
| `startDate` | string (required) | `YYYY-MM-DD` |
| `endDate` | string | `YYYY-MM-DD` inclusive; empty = single day |
| `dataType` | string | `both` (default), `futures`, or `options` |
| `contracts` | array | Optional filter, e.g. `["TXF", "MXF", "TXO"]`. Chinese names also accepted. Empty = all |
| `institutions` | array | Optional filter: `DEALER`, `INVESTMENT_TRUST`, `FOREIGN`. Empty = all three |
| `includePutCallRatio` | boolean | Add one TAIEX options put/call ratio row per trading day |

Example — a month of foreign positioning in TAIEX futures, with sentiment:

```json
{
  "startDate": "2026-07-01",
  "endDate": "2026-07-30",
  "dataType": "futures",
  "contracts": ["TXF", "MXF", "TMF"],
  "institutions": ["FOREIGN"],
  "includePutCallRatio": true
}
```

Example — full daily snapshot, futures and options:

```json
{
  "startDate": "2026-07-30",
  "dataType": "both"
}
```

### Pricing & cost control

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

- Full snapshot (futures + options), one day: 99 records ≈ $0.05
- One month of everything (~22 sessions): ~2,180 records ≈ $1.09
- One contract, one institution, one month: ~22 records ≈ $0.01

Filtering by `contracts` and `institutions` happens before results are stored, so a narrow watchlist stays cheap even over long date ranges.

### Data source & reliability

- Direct from the official Taiwan Futures Exchange 三大法人 CSV exports (`futContractsDateDown`, `callsAndPutsDateDown`, `pcRatioDown`) — no third-party intermediaries
- **Reconciled against a second official feed**: every per-contract figure is summed and matched against the independent TAIFEX OpenAPI aggregate table — all three institutions, all six volume and open-interest columns, exact to the contract
- Contract codes come from the exchange's own product dropdown, not hand-mapped — the report itself prints only Chinese names
- **Identity checks built into the parser**: the exchange prints its own net columns, and the Actor verifies `net = buy − sell` on every volume and open-interest field, logging any violation loudly. Notional value columns are checked within the exchange's ±NT$2k rounding on those columns
- Column-layout guard: if TAIFEX changes the report schema, the run fails loudly instead of returning silently mis-mapped numbers
- **History reaches back about 3 years** (a rolling window on the exchange's side); older dates return no rows, and the Actor says so explicitly rather than returning an unexplained empty dataset
- Weekends skipped automatically; exchange holidays return no rows and are handled cleanly
- TAIFEX publishes this report around 15:00 Taipei time; run after that for the current session

### Use cases

- Tracking foreign institutional net open interest as a directional signal on the TAIEX
- Positioning dashboards combining futures OI with cash-market institutional flows
- Put/call ratio sentiment models on TAIEX options
- Backtesting institutional-positioning factors in Taiwan derivatives
- Monitoring dealer vs investment-trust divergence around expiry weeks
- Research on overseas index futures listed in Taipei (S\&P 500, Nasdaq-100, TOPIX, FTSE 100)

### Related Actors

- [TWSE Institutional Trades](https://apify.com/chamarix/twse-institutional-trades) — the cash-market side of the same three institutions, main board
- [TPEx Institutional Trades](https://apify.com/chamarix/tpex-institutional-trades) — same for the OTC market
- [Taiwan Short Sale & Securities Lending Balance](https://apify.com/chamarix/taiwan-sbl-short-sale-balance) — bear positioning in the cash market
- [Taiwan Margin Trading](https://apify.com/chamarix/taiwan-margin-trading) — retail leverage on the long side
- [Taiwan Shareholding Dispersion (TDCC)](https://apify.com/chamarix/tdcc-shareholding-dispersion) — weekly retail vs whale ownership
- [Taiwan Monthly Revenue](https://apify.com/chamarix/taiwan-monthly-revenue) — monthly revenue of all listed companies

# Actor input Schema

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

Start date in YYYY-MM-DD format. TAIFEX serves this report for roughly the last 3 years only; earlier dates come back empty.

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

End date in YYYY-MM-DD format (inclusive). Leave empty to scrape only the start date.

## `dataType` (type: `string`):

Which report to fetch: futures (23 contracts x 3 institutions = 69 rows/day), options (5 contracts x call/put x 3 institutions = 30 rows/day), or both.

## `contracts` (type: `array`):

Optional list of contract codes to keep, e.g. \['TXF', 'MXF', 'TXO']. Chinese product names such as '臺股期貨' also work. Leave empty for all contracts. Futures: TXF EXF FXF MXF TMF ZEF ZFF STF ETF GTF XIF G2F M1F E4F BTF SOF SHF TJF SPF UNF UDF SXF F1F. Options: TXO TEO TFO STO ETC.

## `institutions` (type: `array`):

Optional list of institution types to keep. Leave empty for all three.

## `includePutCallRatio` (type: `boolean`):

Also output one put/call ratio row per trading day (volume and open-interest ratios for TXO). Adds a handful of rows to the dataset.

## Actor input object example

```json
{
  "startDate": "2026-07-30",
  "endDate": "",
  "dataType": "both",
  "contracts": [
    "TXF",
    "MXF",
    "TXO"
  ],
  "institutions": [],
  "includePutCallRatio": false
}
```

# 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": "2026-07-30",
    "dataType": "both",
    "contracts": [
        "TXF",
        "MXF",
        "TXO"
    ]
};

// Run the Actor and wait for it to finish
const run = await client.actor("chamarix/taifex-institutional-derivatives").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": "2026-07-30",
    "dataType": "both",
    "contracts": [
        "TXF",
        "MXF",
        "TXO",
    ],
}

# Run the Actor and wait for it to finish
run = client.actor("chamarix/taifex-institutional-derivatives").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-07-30",
  "dataType": "both",
  "contracts": [
    "TXF",
    "MXF",
    "TXO"
  ]
}' |
apify call chamarix/taifex-institutional-derivatives --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "command": "npx",
            "args": [
                "mcp-remote",
                "https://mcp.apify.com/?tools=chamarix/taifex-institutional-derivatives",
                "--header",
                "Authorization: Bearer <YOUR_API_TOKEN>"
            ]
        }
    }
}

```

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/5Res7KTRgI0b6M7KP/builds/TvhtyvOFg4SNAdSU9/openapi.json