# Tdcc — Wrapped API

> **You are on:** `https://api.paywithlocus.com/api` | [llms.txt](https://paywithlocus.com/llms.txt) | [docs](https://docs.paywithlocus.com)
>
> Locus runs on multiple environments -- make sure every URL you call matches your expected environment.
> | Environment | Landing | API | Docs |
> |---|---|---|---|
> | Production | paywithlocus.com | api.paywithlocus.com | docs.paywithlocus.com |
> | Beta | beta.paywithlocus.com | api.beta.paywithlocus.com | docs.paywithlocus.com |
> | Stage | stage.paywithlocus.com | api.stage.paywithlocus.com | docs.paywithlocus.com |
>
> If the API URL above doesn't match your expected environment, re-fetch this file from the correct domain.

> Access Taiwan stock market data including shareholder distribution, custody statistics, and company metadata directly from the official Taiwan Depository & Clearing Corporation records. Search stocks by name, retrieve bulk shareholder information, and monitor individual securities custody trends to analyze market ownership patterns and investment positions.

**Category:** Finance & Markets | **Website:** [tdcc.com.tw/](https://tdcc.com.tw/) | **Docs:** [parse.bot/marketplace/4ea402d2-9724-49c3-947f-008bf4959cd7/tdcc-com-tw-api](https://parse.bot/marketplace/4ea402d2-9724-49c3-947f-008bf4959cd7/tdcc-com-tw-api)

Pay-per-use API proxy. Each call is automatically billed to your wallet in USDC.

## Access

**Base URL:** `https://api.paywithlocus.com/api/wrapped/parse-tdcc-com-tw-api-4ea402d2/`
**Auth:** `Authorization: Bearer <LOCUS_API_KEY>`

## Endpoints

### get_available_dates

Retrieve the list of available data dates in YYYYMMDD format for the shareholder distribution query. Returns weekly dates going back approximately one year, ordered newest first.

**Estimated cost:** Metered

_No parameters required._

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-tdcc-com-tw-api-4ea402d2/get_available_dates \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'
```

### get_bulk_shareholder_distribution

Fetch bulk shareholder distribution data for all stocks. Equivalent to get_open_data with data_id '1-5'. Response time approximately 10-15 seconds. Each record includes data date, stock code, shareholding bracket level, number of holders, number of shares, and percentage of total custody shares.

**Estimated cost:** Metered

_No parameters required._

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-tdcc-com-tw-api-4ea402d2/get_bulk_shareholder_distribution \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'
```

### get_open_data

Fetch bulk data from the TDCC Open Data portal by dataset ID. Returns parsed CSV data. Response times can be slow (10-30 seconds). Dataset IDs include '1-1' for security basic info, '1-5' for shareholder distribution, '2-22' for listed custody monthly, '2-23' for OTC custody monthly, '2-24' for emerging custody monthly.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `data_id` | string | Yes | The Open Data dataset ID (e.g. '1-1' for security basic info, '1-5' for shareholder distribution, '2-22' for listed custody monthly). |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-tdcc-com-tw-api-4ea402d2/get_open_data \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"data_id":"<string>"}'
```

### get_securities_custody_individual_monthly

Fetch monthly custody change statistics for individual stocks. Returns data on custody share changes month-over-month. Data uses ROC calendar year format (e.g. 11503 = March 2026). Each record includes year-month, stock code, stock name, current and previous month custody in thousands of shares, change amount and percentage, total issued shares, and number of depository shareholders.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `market_type` | string | No | The market type: 'listed', 'otc', or 'emerging'. |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-tdcc-com-tw-api-4ea402d2/get_securities_custody_individual_monthly \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"market_type":"<string>"}'
```

### get_security_basic_info

Fetch basic security information for all listed, OTC, and emerging stocks. Equivalent to get_open_data with data_id '1-1'. Response time approximately 20-30 seconds. Each record includes stock code, name, market type, transfer agent, security status, par value, and update date.

**Estimated cost:** Metered

_No parameters required._

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-tdcc-com-tw-api-4ea402d2/get_security_basic_info \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'
```

### get_shareholder_distribution

Query the Shareholder Distribution Table for a specific stock ID and date. Returns the number of shareholders and shares held in each shareholding bracket. If date is omitted, the latest available date is used. Each row includes the bracket range, number of holders, number of shares, and percentage of total custody shares.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `date` | string | No | Data date in YYYYMMDD format. Omitting returns the latest available date. |
| `stock_id` | string | Yes | The numeric stock ID (e.g. '2330' for TSMC, '2317' for Hon Hai). |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-tdcc-com-tw-api-4ea402d2/get_shareholder_distribution \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"date":"<string>","stock_id":"<string>"}'
```

### search_stock_by_name

Search for stocks by Chinese company name. Returns matching stock name suggestions. Only Chinese name queries are supported; numeric stock IDs will return empty results.

**Estimated cost:** Metered

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `query` | string | Yes | Chinese company name or partial name to search (e.g. '台積電', '鴻海'). |

```bash
curl -X POST https://api.paywithlocus.com/api/wrapped/parse-tdcc-com-tw-api-4ea402d2/search_stock_by_name \
  -H "Authorization: Bearer YOUR_LOCUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query":"<string>"}'
```