# Taiwan Short Sale & Securities Lending Balance (TWSE + TPEx) (`chamarix/taiwan-sbl-short-sale-balance`) Actor

Daily short interest for all 2,200+ Taiwan listed & OTC stocks: margin short sale (融券) and securities borrowing & lending (借券賣出) balances in one normalized JSON schema. Official TWSE/TPEx data for squeeze screening, bear positioning and quant research.

- **URL**: https://apify.com/chamarix/taiwan-sbl-short-sale-balance.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 Short Sale & Securities Lending Balance (TWSE + TPEx)

Get structured JSON access to **daily short interest for every Taiwan-listed stock** — both short-selling mechanisms, both markets, one normalized schema.

Taiwan splits short selling across two separate systems, reported in separate places:

- **融券 (margin short sale)** — retail-dominated, borrowed through the margin financing system, subject to mandatory recall before shareholder meetings
- **借券賣出 (SBL short sale)** — the securities borrowing & lending system used by foreign institutions, hedge funds and market makers; typically **10–100× larger** than margin shorts on liquid names

Looking at only one of them gives you a badly incomplete picture of bear positioning. This Actor pulls both, for the main board (TWSE) and the OTC market (TPEx / 櫃買中心), and adds the combined total.

### Why this data matters

- **Total short balance** is the real short-interest number for a Taiwan stock — the margin-only figure most screeners use misses the institutional side entirely
- **Short squeeze setups**: margin shorts face forced covering around 停止過戶 (book-closure) dates; a high 融券餘額 into a shareholder meeting is a classic Taiwan squeeze catalyst
- **Next-day SBL quota** (30% of the trailing 30-day average volume) shows how much more institutions are *allowed* to short tomorrow — a hard ceiling on further pressure
- **Suspension flags** identify stocks where short selling is halted outright (停券 / 停止借券賣出), often a signal of prior squeeze intervention
- Day-over-day balance deltas are a standard factor in Taiwan quant models

This is the natural companion to margin *long* data — see [Taiwan Margin Trading](https://apify.com/chamarix/taiwan-margin-trading) for the 融資 side.

### Output

One record per stock per trading day, 24 normalized fields. **All quantities are in shares (股)**, matching the exchange's own reporting for this report — note that the margin balance report publishes lots (張); 1 lot = 1,000 shares.

```json
{
  "date": "2026-07-28",
  "market": "TWSE",
  "stock_code": "2330",
  "stock_name": "台積電",
  "short_balance_prev": 64000,
  "short_sell": 54000,
  "short_buy": 5000,
  "short_redemption": 0,
  "short_balance": 113000,
  "short_balance_change": 49000,
  "short_quota_next_day": 6483092516,
  "sbl_balance_prev": 13144514,
  "sbl_sell": 227000,
  "sbl_return": 90000,
  "sbl_adjustment": 0,
  "sbl_balance": 13281514,
  "sbl_balance_change": 137000,
  "sbl_quota_next_day": 11869217,
  "total_short_balance": 13394514,
  "total_short_balance_prev": 13208514,
  "total_short_balance_change": 186000,
  "note": "",
  "note_flags": []
}
```

| Field | Meaning |
|---|---|
| `short_sell` / `short_buy` | 融券賣出 / 融券買進 (new margin shorts / short covering) |
| `short_redemption` | 現券償還 (share repayment) |
| `short_balance_prev` / `short_balance` | 前日 / 今日融券餘額 |
| `short_balance_change` | Day-over-day change in margin short balance |
| `short_quota_next_day` | 次一營業日限額 — regulatory cap (25% of free float) |
| `sbl_sell` / `sbl_return` | 借券賣出當日賣出 / 當日還券 |
| `sbl_adjustment` | 當日調整 (position transfers between trading categories, error corrections) |
| `sbl_balance_prev` / `sbl_balance` | 前日 / 當日借券賣出餘額 |
| `sbl_balance_change` | Day-over-day change in SBL short balance |
| `sbl_quota_next_day` | 次一營業日可借券賣出限額 — 30% of the trailing 30-day average volume |
| `total_short_balance` | `short_balance + sbl_balance` — combined bear positioning |
| `note` / `note_flags` | Raw exchange flags and their decoded meanings |

`note_flags` decodes the exchange's single-letter codes: `X` 停券, `Y` 未取得信用交易資格, `V` 停止借券賣出, `%` 信用額度分配, `Z` 借券賣出已達總量控管, `!` 停止買賣.

Both balances satisfy the accounting identities the exchange prints on the report itself:

- 融券: `prev + sell - buy - redemption = balance`
- 借券賣出: `prev + sell - return + adjustment = balance`

The Actor checks both at parse time and logs any violation loudly.

### Input

| Field | Type | Description |
|---|---|---|
| `startDate` | string (required) | `YYYY-MM-DD` |
| `endDate` | string | `YYYY-MM-DD` inclusive; empty = single day |
| `market` | string | `both` (default), `twse`, or `tpex` |
| `stockCodes` | array | Optional filter, e.g. `["2330", "5274"]`. Empty = all (~2,200 stocks/day) |
| `minTotalShortBalance` | integer | Only return stocks with combined short balance ≥ this many shares. `0` = no filter |

Example — one month of short interest for three tickers:

```json
{
  "startDate": "2026-07-01",
  "endDate": "2026-07-28",
  "market": "both",
  "stockCodes": ["2330", "2317", "5274"]
}
```

Example — daily screen for meaningfully shorted stocks only:

```json
{
  "startDate": "2026-07-28",
  "market": "both",
  "minTotalShortBalance": 1000000
}
```

### Pricing & cost control

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

- Full market (TWSE + TPEx), one day: ~2,220 records ≈ $1.11
- Filtered to 5 tickers, one month: ~200 records ≈ $0.10
- `minTotalShortBalance: 1000000`, one day: a few hundred records

Most Taiwan stocks carry little or no short interest, so `minTotalShortBalance` is usually the cheapest way to run a market-wide screen.

### Data source & reliability

- Direct from the official TWSE (`TWT93U`) and TPEx 信用額度總量管制餘額表 feeds — no third-party intermediaries
- Historical data verified back to at least 2024 for both markets
- Weekends skipped automatically; market holidays return no rows and are skipped
- Column-layout guard: if either exchange changes its schema, the run fails loudly instead of returning silently mis-mapped numbers
- Values cross-verified against two independent official feeds (`MI_MARGN` for the margin short side, `openapi.twse.com.tw/v1/SBL/TWT96U` for next-day SBL quotas)
- The exchanges refresh this report twice each evening (~20:30 and ~22:30 Taipei time); run after 22:30 for the settled figures

### Use cases

- Short-squeeze screeners — high margin short balance heading into book-closure dates
- True short-interest ratios for Taiwan equities (margin + SBL, not margin alone)
- Tracking foreign institutional bear positioning via the SBL side
- Risk dashboards flagging stocks near their SBL quota ceiling or under a short-selling suspension
- Academic and quant research on short-selling constraints in an emerging market

### Related Actors

- [Taiwan Margin Trading](https://apify.com/chamarix/taiwan-margin-trading) — the 融資 long side, same markets and date range
- [TWSE Institutional Trades](https://apify.com/chamarix/twse-institutional-trades) — daily foreign/trust/dealer flows, main board
- [TPEx Institutional Trades](https://apify.com/chamarix/tpex-institutional-trades) — same for the OTC market
- [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.

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

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

## `market` (type: `string`):

Which market to fetch: both (TWSE listed + TPEx OTC), twse only, or tpex only.

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

Optional list of stock codes to filter (e.g., \['2330', '5274']). Leave empty to get all stocks.

## `minTotalShortBalance` (type: `integer`):

Only output stocks whose combined short balance (融券 + 借券賣出, in shares) is at least this value. Most stocks carry little or no short interest, so a threshold such as 1000000 cuts result count — and cost — dramatically. 0 = no filter.

## Actor input object example

```json
{
  "startDate": "2026-07-28",
  "endDate": "",
  "market": "both",
  "stockCodes": [
    "2330",
    "2317",
    "5274"
  ],
  "minTotalShortBalance": 0
}
```

# 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-28",
    "market": "both",
    "stockCodes": [
        "2330",
        "2317",
        "5274"
    ],
    "minTotalShortBalance": 0
};

// Run the Actor and wait for it to finish
const run = await client.actor("chamarix/taiwan-sbl-short-sale-balance").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-28",
    "market": "both",
    "stockCodes": [
        "2330",
        "2317",
        "5274",
    ],
    "minTotalShortBalance": 0,
}

# Run the Actor and wait for it to finish
run = client.actor("chamarix/taiwan-sbl-short-sale-balance").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-28",
  "market": "both",
  "stockCodes": [
    "2330",
    "2317",
    "5274"
  ],
  "minTotalShortBalance": 0
}' |
apify call chamarix/taiwan-sbl-short-sale-balance --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "command": "npx",
            "args": [
                "mcp-remote",
                "https://mcp.apify.com/?tools=chamarix/taiwan-sbl-short-sale-balance",
                "--header",
                "Authorization: Bearer <YOUR_API_TOKEN>"
            ]
        }
    }
}

```

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/acts/2kjysU2Wp4aTBM46m/builds/kcbIMjDPvd09xWFiQ/openapi.json