# Taiwan Gold Spot — 櫃買黃金現貨行情與造市商 API (`chamarix/taiwan-gold-spot`) Actor

The Taipei Exchange's physical gold board back to 2015: daily VWAP, traded high/low, market-maker closing quotes and spread, every securities firm's turnover and every print by firm and price. Quoted in NT$ per 台錢, per gram and per troy ounce, with the 2025 台兩→台錢 unit change handled.

- **URL**: https://apify.com/chamarix/taiwan-gold-spot.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/actors/running/actors-in-store.md#pay-per-event

## What's an Apify Actor?

An Actor is a serverless cloud program that runs on the Apify platform. It has two run modes.
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.

Apify vocabulary and the platform model are defined once, in the agent quickstart at https://apify.com/agents.md.

## 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.

Do not guess an integration path. Every one of them is in the agent quickstart at https://apify.com/agents.md: the Apify MCP server, Agent Skills with the Apify CLI, the JavaScript and Python clients, the REST API, and the account-free path for an agent with no human to sign in. It also carries the rule on stating cost before the first paid run.

For examples already wired to this Actor's own input schema, see the [API](#api) section below.

Each client library has reference documentation the quickstart does not restate: [JavaScript/TypeScript](https://docs.apify.com/api/client/js/docs.md) (`npm install apify-client`) and [Python](https://docs.apify.com/api/client/python/docs.md) (`pip install apify-client`).

# README

## Taiwan Gold Spot (櫃買黃金現貨行情) API

Daily prices, market-maker quotes and the full participant flow for **the Taipei Exchange's physical gold board** — the only regulated spot gold market in Taiwan — as structured JSON, back to 2015.

This is a real exchange-traded market that almost nobody has ever pulled data from. Gold in Taiwan is usually bought as a bank passbook product at whatever price the bank posts; the TPEx gold board is the venue where that price is actually discovered, with two market makers quoting and 200-odd securities-firm branches dealing against them. The exchange publishes seven separate reports about it every session and joins none of them. This Actor returns all seven, reconciled against each other, with the weights converted to something the rest of the world can read.

### Output

One dataset, seven record types, told apart by `record_type`. A real daily bar:

```json
{
  "record_type": "daily_quote",
  "date": "2026-09-24",
  "product_code": "AU9901",
  "product_name": "臺銀金",
  "average_price": 16508.2,
  "average_price_per_gram": 4402.1867,
  "average_price_per_troy_ounce": 136926.8419,
  "high": 16559.0,
  "low": 16422.0,
  "last_best_bid": 16427.0,
  "last_best_ask": 16485.0,
  "closing_spread": 58.0,
  "closing_quote": 16485.0,
  "closing_quote_equals_last_best_ask": true,
  "change": -112.9,
  "change_percent": -0.68,
  "previous_average_price": 16621.1,
  "volume_as_published": 1473.0,
  "volume_unit_as_published": "qian",
  "volume_qian": 1473.0,
  "volume_grams": 5523.75,
  "turnover": 24316570,
  "trades": 518,
  "average_price_rebuilt": 16508.1942,
  "average_price_residual_percent": 3.5e-05,
  "average_price_matches": true,
  "quality_flags": []
}
```

And the market makers' closing quote, which exists even on a session with no trades at all:

```json
{
  "record_type": "closing_mid",
  "date": "2026-09-24",
  "product_code": "AU9901",
  "highest_bid": 16427.0,
  "lowest_ask": 16485.0,
  "closing_mid": 16456.0,
  "closing_mid_per_gram": 4388.2667,
  "spread": 58.0,
  "spread_percent": 0.352455,
  "closing_mid_rebuilt": 16456.0,
  "closing_mid_matches": true
}
```

The other five are `market_summary` (one row a session: totals, advancing/declining, market-maker count), `branch_turnover` (every dealing branch, both sides of the book), `broker_turnover` (securities firms aggregated, with how many branches dealt), `market_maker_turnover` (the two bullion banks) and `dealer_trade` — **every individual print**, by product, securities firm and price.

### Units, stated once, because this is where the data bites

Taiwanese gold is weighed in Taiwanese units and getting this wrong scales everything by ten:

| | Meaning |
|---|---|
| 台錢 (qian) | The trading unit since **2025-10-01**. Exactly 3.75 g. |
| 台兩 (tael) | The trading unit **before** that. Exactly 10 台錢 = 37.5 g. |
| `volume_qian`, `volume_grams` | Normalised across both eras. **Sum these**, not the published column. |
| `volume_as_published` + `volume_unit_as_published` | The exchange's own figure and its own unit, kept verbatim. |
| All prices | **NT$ per 台錢, in both eras.** The price unit never changed — only the volume unit did. |
| `*_per_gram`, `*_per_troy_ounce` | Derived, so the number can sit next to a London or COMEX quote. |

**The unit change is the single biggest trap in this dataset.** On 2025-09-23 the board's volume column was in 台兩; on 2025-10-01 it was in 台錢, and the board was shut in between. A series that concatenates the two is wrong by a factor of ten across the join, and it is wrong in a way that still looks like gold volume.

This Actor does not hard-code that date. The exchange names the unit inside the column header — `成交量(台兩)` versus `成交量(台錢)` — so the unit is read from the payload itself, every session. A header that names no unit at all is refused rather than assumed, because the next change would otherwise pass silently.

### Verification

Seven reports describing one session is seven chances to check the parse, and the checks are the point of this Actor. None of the cross-report ones need a tolerance — they are the same integers printed in different tables, so they either agree exactly or a column was read wrong, and a disagreement fails the run instead of publishing a row.

- **The daily bar's totals equal the session summary's totals.** Turnover, volume and trade count, from two independently published reports.
- **Every participant is on one side of the book.** The branch turnover table includes the market makers, so its buy total and its sell total must each equal the market's turnover.
- **The securities firms and the market makers are mirror images.** Firms buy what the makers sell. `broker_turnover` buy total equals `market_maker_turnover` sell total, and the other way round — which is also what makes the two bullion banks' role visible rather than assumed.
- **Every print adds up to the day.** The sum of all buy quantities in the per-trade report equals the sum of all sell quantities, and both equal the market's volume, to the 台錢.
- **The daily high and low are the highest and lowest prints.** Checked against the per-trade report's own minimum and maximum, to the cent. This is the strongest column-alignment check here because it ties the summary bar to the individual trades behind it.
- **Buy plus sell equals turnover** on every row of all three turnover tables.
- **The average price is rebuilt from turnover over volume**, and the closing average from the midpoint of the two quotes printed beside it — which is precisely how the exchange's own footnote defines 收市均價.

The two rebuilt figures are the ones that need a stated tolerance, and both are derived rather than picked:

- The **closing average** is compared within *half of the last digit the report printed* — 0.005 against today's two-decimal reports, 0.05 against the one-decimal reports of 2016. The midpoint itself is exact arithmetic; all the slack is in the rounding of the number it is checked against.
- The **average price** is checked at 0.5%, deliberately loose, because its job is to catch a wrong weight unit rather than to audit the exchange's rounding. A correct parse lands within 0.001%; a 台兩/台錢 mix-up lands 900% out. Tightening this to the observed residual would fail on ordinary sessions as soon as the exchange's per-trade rounding moved, without catching anything a 0.5% band misses.

Independently of the arithmetic, the parse was checked against a **second publication path**: the exchange also ships these reports as Big5 CSV downloads, and the JSON columns this Actor reads match those files header for header and value for value.

### Two semantics the column names get wrong

Both were found by cross-checking, and both would silently mislead:

- **`最後` is not the last traded price.** In every session sampled it equals the closing best *ask*, to the cent. It is published here as `closing_quote`, with `closing_quote_equals_last_best_ask` recording the fact on each row rather than asserting it. If you want the session's value use `average_price`; if you want an actual last print, the `dealer_trade` rows have them.
- **The closing bid can sit below the day's traded low.** On 2026-09-22 AU9901 printed no lower than 16,526 yet closed bid at 16,493. That is not an error — the market makers moved their quote down after the last trade. Any validation that checks quotes against a traded range will fail a correct parse, which is why this Actor checks only the average against the high and low.

### What you can ask for

- `recordTypes` — any of the seven. Each is one request per session, so the cost is feeds × weekdays. The default is the three price feeds.
- `startDate` / `endDate` — the session range. Weekends are skipped automatically; public holidays answer empty and are counted rather than treated as failures.
- `productCodes` — `AU9901` or `AU9902`.
- `maxRequests` — a cap, because all seven feeds over a decade runs to tens of thousands of calls.

### Limitations, stated plainly

- **Two products, two market makers, one maker each.** AU9901 is made by Bank of Taiwan, AU9902 by First Bank, and the exchange's own 平均每檔黃金之造市商家數 has been 1.00 throughout. There is no competing quote in either name, and the spread should be read with that in mind.
- **This is a thin market.** A session is hundreds of prints, not thousands, and the board does go a day without trading. An empty session is not an error; an entire empty range is, and fails the run.
- **The 主要機構法人 (major institutional investors) reports are empty.** Both the daily and weekly versions return no rows on every date sampled across the whole archive, so they are not included. An empty table is not published as if it were data.
- **The weekly, monthly and yearly reports are not included.** They are aggregations of the daily series this Actor already returns, and can be computed from it.
- **The 當日行情表 snapshot ignores its own date parameter.** `gold/latest` accepts `date=` and returns today's figures regardless — a request for 2020 comes back with this morning's prices, looking entirely plausible. This Actor does not use it; the dated reports are what it reads.
- **Prices before 2015-01-02 are not available**, and the closing-quote report starts 2015-11-30, which is what its own footnote says.
- **`market_summary` behaves differently from every other feed on a quiet day.** On a weekday the board was open with no print at all, it answers normally with zeros while the other six answer 無資料. That row is kept, flagged `had_trading: false` — it is the only place the difference between "closed" and "open but nobody traded" survives.

### Source

Taipei Exchange (證券櫃檯買賣中心), seven official reports on the gold spot board: `gold/des410` (daily bars), `gold/dss411` (closing quotes), `gold/highlight` (session summary), `gold/dss401`, `gold/dss402` and `gold/dss403` (branch, firm and market-maker turnover) and `gold/dss404` (individual prints).

### Taiwan Market Data Suite

This Actor is part of a suite of 44 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:**

- [taiwan-corporate-bonds](https://apify.com/chamarix/taiwan-corporate-bonds) — Every corporate, bank & Formosa bond — terms, balance, ratings & ISINs, daily OTC trades since 2005 and USD bond fair values since 2017
- [taiwan-securities-lending-balance](https://apify.com/chamarix/taiwan-securities-lending-balance) — Shares on loan for every stock since 2004 by lending channel, every SLB trade with its borrow fee rate, and each firm's lending book
- [taiwan-ipo-listings](https://apify.com/chamarix/taiwan-ipo-listings) — Every TWSE & TPEx listing application since 2000 from filing to first trading day — review, approval, price, underwriter & withdrawals, plus delistings
- [taiwan-board-directors](https://apify.com/chamarix/taiwan-board-directors) — Every independent director's career and other board seats linked to stock codes, board rosters, chair/CEO duality & director elections
- [taiwan-broker-financials](https://apify.com/chamarix/taiwan-broker-financials) — Every securities firm's monthly balance sheet & P\&L since 2013, full trial balance, and the register of firms & branches
- [taiwan-short-sale-eligibility](https://apify.com/chamarix/taiwan-short-sale-eligibility) — Can it be shorted today? Below-close short list, shares available to borrow, borrow fees, margin haircuts & forced cover dates
- [taiwan-gold-spot](https://apify.com/chamarix/taiwan-gold-spot) — The Taipei Exchange physical gold board since 2015 — daily VWAP, traded high/low, market-maker spread and every print by firm and price
- [taiwan-convertible-bonds](https://apify.com/chamarix/taiwan-convertible-bonds) — Daily bars for every convertible bond on the Taipei Exchange, with conversion price, conversion window, put date & put price
- [taiwan-corporate-action-prices](https://apify.com/chamarix/taiwan-corporate-action-prices) — Capital reductions, par value changes & ETF splits — the official reopening price & adjustment factor for every price discontinuity since 2011
- [taiwan-ipo-subscription](https://apify.com/chamarix/taiwan-ipo-subscription) — Every IPO ballot since 2006 & every competitive auction since 2016 — odds, ticket cost, reserve & bid-to-cover
- [taiwan-intraday-5sec-stats](https://apify.com/chamarix/taiwan-intraday-5sec-stats) — Market-wide order book & all sector indices every 5 seconds since 2004, 3,241 rows a session
- [taiwan-stock-daily-quotes](https://apify.com/chamarix/taiwan-stock-daily-quotes) — Daily OHLCV, VWAP, P/E, price-to-book & dividend yield for every listed/OTC stock since 2004
- [taiwan-index-history](https://apify.com/chamarix/taiwan-index-history) — Daily TAIEX & TPEx index history since 1990 with market turnover, the total-return index & all 273 TWSE indices
- [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-director-compensation](https://apify.com/chamarix/taiwan-director-compensation) — Board pay for 1,950+ companies, parent vs consolidated scope, with EPS, ROE & profit on the same row
- [taiwan-esg-disclosures](https://apify.com/chamarix/taiwan-esg-disclosures) — 21 ESG topics for 1,950+ companies — Scope 1/2/3 emissions, energy, water, waste, pay, board & climate risk
- [taiwan-dividend-calendar](https://apify.com/chamarix/taiwan-dividend-calendar) — Ex-dividend / ex-rights dates, reference prices & payouts back to 2003
- [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-short-sale-volume](https://apify.com/chamarix/taiwan-short-sale-volume) — Daily short sale turnover per stock — margin & borrowed lots, value and implied price, since 2008
- [taiwan-day-trading-stats](https://apify.com/chamarix/taiwan-day-trading-stats) — Day-trading volume, value & ratio per stock since 2014
- [taiwan-odd-lot-trading](https://apify.com/chamarix/taiwan-odd-lot-trading) — Both odd-lot sessions per stock — intraday & after-hours, shares, turnover, OHLC & quotes since 2004
- [taiwan-broker-rankings](https://apify.com/chamarix/taiwan-broker-rankings) — Securities-firm turnover, market share & the top firms in each hot stock on the OTC board since 2007
- [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
- [taiwan-futures-daily](https://apify.com/chamarix/taiwan-futures-daily) — Daily bars, settlement price & open interest for all 384 TAIFEX futures contracts since 1998, with the large-trader report
- [taifex-institutional-derivatives](https://apify.com/chamarix/taifex-institutional-derivatives) — Institutional futures & options positions (TAIFEX), incl. put/call ratio
- [taifex-options-chain](https://apify.com/chamarix/taifex-options-chain) — Full options chain by strike & expiry, both sessions, with the exchange's own Delta, since 2001
- [taiwan-warrants-daily](https://apify.com/chamarix/taiwan-warrants-daily) — Daily quotes, strike, expiry & moneyness for every listed/OTC warrant since 2004
- [taiwan-government-bonds](https://apify.com/chamarix/taiwan-government-bonds) — Central government bond benchmark yields, the full yield curve & issuance master, with staleness stated
- [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
- [taiwan-block-trades](https://apify.com/chamarix/taiwan-block-trades) — Every block trade (鉅額交易) with price, size & basket constituents since 2005
- [taiwan-shareholder-meetings](https://apify.com/chamarix/taiwan-shareholder-meetings) — Shareholder meeting dates, book closure periods & e-voting since 2005
- [taiwan-emerging-stock-quotes](https://apify.com/chamarix/taiwan-emerging-stock-quotes) — Emerging (興櫃) board quotes, pre-IPO register & history since 2003
- [taiwan-etf-regular-investment](https://apify.com/chamarix/taiwan-etf-regular-investment) — Monthly regular savings plan (定期定額) rankings for stocks & ETFs since 2020
- [taiwan-treasury-stock-buybacks](https://apify.com/chamarix/taiwan-treasury-stock-buybacks) — Every treasury-stock buyback (庫藏股) filing, plan vs execution, since 2000

**Property market:**

- [taiwan-real-estate-transactions](https://apify.com/chamarix/taiwan-real-estate-transactions) — Actual registered sale, presale & lease prices (實價登錄) for all 22 cities since 2012

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

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

Seven official reports, written to one dataset and told apart by record_type. Each one is a single request per session, so the cost is the number of feeds times the number of weekdays in your range.

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

First session to include. Defaults to fourteen days before the end date, which is long enough to contain a trading day even over Lunar New Year. The board's reports begin 2015-01-02; the closing-quote report begins 2015-11-30, as its own footnote says, and earlier dates are skipped rather than requested.

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

Last session to include, inclusive. Defaults to today in Taipei. Saturdays and Sundays are skipped automatically; public holidays answer empty and are counted, not treated as failures.

## `productCodes` (type: `array`):

Keep only these products. The board has only ever listed two: AU9901 (臺銀金, market-made by Bank of Taiwan) and AU9902 (一銀金, First Bank). Leave empty for both.

## `maxRequests` (type: `integer`):

A safety cap, because a multi-year backfill of all seven feeds runs to thousands of calls. When the plan exceeds the cap the most recent sessions are kept. Set 0 to lift it.

## Actor input object example

```json
{
  "recordTypes": [
    "quotes",
    "closing_mid",
    "market_summary"
  ],
  "startDate": "",
  "endDate": "",
  "productCodes": [],
  "maxRequests": 400
}
```

# Actor output Schema

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

Seven official reports on the Taipei Exchange gold board — daily bars, market-maker closing quotes, session summary, three levels of participant turnover and every individual print — in one dataset, told apart by record_type.

# 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 = {
    "recordTypes": [
        "quotes",
        "closing_mid",
        "market_summary"
    ],
    "startDate": "",
    "endDate": "",
    "productCodes": [],
    "maxRequests": 400
};

// Run the Actor and wait for it to finish
const run = await client.actor("chamarix/taiwan-gold-spot").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 = {
    "recordTypes": [
        "quotes",
        "closing_mid",
        "market_summary",
    ],
    "startDate": "",
    "endDate": "",
    "productCodes": [],
    "maxRequests": 400,
}

# Run the Actor and wait for it to finish
run = client.actor("chamarix/taiwan-gold-spot").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 '{
  "recordTypes": [
    "quotes",
    "closing_mid",
    "market_summary"
  ],
  "startDate": "",
  "endDate": "",
  "productCodes": [],
  "maxRequests": 400
}' |
apify call chamarix/taiwan-gold-spot --silent --output-dataset

```

## MCP server setup

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

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/Z7Zrjh3qRfzpgs2IC/builds/Jft72uPN9WixsjAPv/openapi.json