# clarifindata 金晰數據

> Lean Taiwan-stock market-data API. Subscriptions for humans, x402 micropayments for AI agents.
> Base URL: https://clarifindata.com/api

## Authentication

Single method, standard Bearer (RFC 6750):

```
Authorization: Bearer YOUR_API_KEY
```

Get a Free key by signing up at https://clarifindata.com/signup —
no shared demo key is published (anyone could drain its rate-limit).
Lite / Plus keys require a paid subscription via /#pricing.

## Endpoints

- `GET  /v1/data`                    — list every dataset (no auth)
- `GET  /v1/data/{dataset}`          — query a dataset
    · Query params: `stock_id`, `start`, `end`, `limit` (<=10000)
    · Returns `{dataset, tier_used, count, data: [...]}`
- `GET  /v1/key/info`                — what tier am I on, how many calls left this hour
- `POST /v1/ask`  (Plus)             — natural-language -> SQL -> rows; body `{question}`
- `GET  /v1/agent/{dataset}`         — same data, x402/USDC pay-per-call (no signup)
- `GET  /llms.txt`                   — this manifest
- `GET  /healthz`                    — liveness

## Tier model

- **Free**: 44 datasets (technical / chips / fundamentals / derivatives / other).
  Includes per-stock daily K, three-major-investor flows, monthly revenue.
  Rate: 600 req/hour.
- **Lite NT$149/month**: Free + ~22 essentials (weekly/monthly K, market-cap,
  industry chain, halt + price-limit, futures large-traders + settlement).
  Rate: 3,000 req/hour.
- **Plus NT$299/month**: Lite + niche (adjusted-price, tick history, 5-sec index,
  convertibles, night-session, Fear&Greed, US K-bars) + natural-language /ask.
  Rate: 10,000 req/hour.

## Rate-limit headers (every authenticated response)

- `X-RateLimit-Limit` — calls per hour for your tier
- `X-RateLimit-Remaining` — calls left this hour
- `X-RateLimit-Tier` — `free` / `lite` / `plus`
- Over the cap returns `429` + body `{retry_after_seconds}`.

## x402 micropayments (for autonomous agents)

Unauthenticated `GET /v1/agent/{dataset}` returns `402 Payment Required` with a
`payment-required` header (base64-encoded EIP-712 intent):
- scheme=`exact`, network=`eip155:84532` (Base Sepolia)
- USDC contract + atomic-unit amount (1000 = $0.001) + pay-to address

Sign with your wallet, retry the request with `X-PAYMENT: <signed-base64>`.

## Datasets

_73 datasets, all live with real data, refreshed daily._

### Free (38)

- `TaiwanStockOverview` — 上市櫃股票總覽（代號、名稱、產業、掛牌日）
- `TaiwanStockOverviewIncludeWarrant` — 台股總覽（含權證）
- `TaiwanStockTradingDate` — 台股交易日曆
- `TaiwanStockSectorPrice` — 台灣類股股價表
- `TaiwanStockPER` — 個股 PER / PBR / 殖利率
- `TaiwanWeightedIndex` — 台股加權指數
- `TaiwanStockDayTradingInfo` — 當日沖銷交易標的及成交量值
- `TaiwanReturnIndex` — 加權、櫃買報酬指數
- `TaiwanStockTotalMarginPurchaseShortSale` — 整體市場融資融券
- `TaiwanStockTotalInstitutionalInvestors` — 整體市場三大法人買賣
- `TaiwanStockSecuritiesLending` — 借券餘額
- `TaiwanDailyShortSaleBalances` — 信用額度總量管制餘額表 (融券 + 借券賣出, per-stock)
- `TaiwanStockBlockTrade` — 鉅額交易日成交資訊 (TWSE BFIAUU, 2005-04+)
- `TaiwanStockCreditLimit` — 信用額度總量管制餘額
- `TaiwanStockBrokerInfo` — 證券商資訊表
- `TaiwanStockCashFlowsStatement` — 現金流量表 — 營業/投資/籌資活動現金流
- `TaiwanStockFinancialStatement` — 綜合損益表 — 每季 EPS/營收/淨利
- `TaiwanStockBalanceSheet` — 資產負債表 — 含一般業/金融/金控/保險/證券期貨/異業
- `TaiwanStockDividend` — 股利政策表
- `TaiwanStockDividendResult` — 除權除息計算結果表 — 含參考價
- `TaiwanStockCapitalReductionReferencePrice` — 減資恢復買賣參考價格
- `TaiwanStockDelisting` — 台股下市資料表
- `TaiwanStockSplitPrice` — 台股分割後參考價 (TWSE TWTCAU)
- `TaiwanStockChangeFaceReference` — 變更面額恢復買賣參考價格 (TWSE TWTB8U)
- `TaiwanFutureOptionDailyTotalOverview` — 期貨、選擇權日成交資訊總覽 — 大盤量值匯總
- `TaiwanFutureOptionTickRealtime` — 期貨、選擇權契約規格總覽 (TAIFEX 契約主檔)
- `TaiwanFuturesDaily` — 期貨日成交資訊 — TX/MTX/TE/TF/TGF
- `TaiwanOptionDaily` — 選擇權日成交資訊 — TXO/TEO/TFO
- `TaiwanFuturesInstitutionalInvestors` — 期貨三大法人 — 多空淨額口數
- `TaiwanOptionInstitutionalInvestors` — 選擇權三大法人 — 多空淨額口數
- `TaiwanRelatedNews` — 台股相關新聞
- `CurrencyCirculation` — 通貨發行額 / currency in circulation (FRED, 月頻)
- `GoldPrice` — 黃金期貨 (Yahoo GC=F)
- `CrudeOilPrices` — 原油期貨 (WTI / Brent)
- `USStockPrice` — 美股股價 (日 K)
- `ExchangeRate` — 外幣對台幣資料表 (19 種幣別)
- `CentralBankRate` — 央行政策利率 (US/EU/UK/JP/CA/CH/AU/KR/CN)
- `USBondYield` — 美國國債殖利率 (3M / 5Y / 10Y / 30Y)

### Lite (31)

- `TaiwanStockPrice` — 個股日 K (TWSE STOCK_DAY)
- `TaiwanStockPriceAdj` — 還原股價 — 除權息調整
- `TaiwanStockWeekPrice` — 台股週 K — 由日 K 聚合
- `TaiwanStockMonthPrice` — 台股月 K — 由日 K 聚合
- `TaiwanStock10Year` — 個股十年線 — 10 年滾動均線
- `TaiwanStockTradingHaltAnnouncement` — 台股注意交易資訊累計次數異常
- `TaiwanStockSuspendDayTrading` — 暫停先賣後買當沖預告表
- `TaiwanStockDailyPriceLimit` — 每日漲跌停價 — 前收 × ±10% 計算
- `TaiwanStockMarginPurchaseShortSale` — 個股融資融券
- `TaiwanStockInstitutionalInvestorsBuySell` — 個股三大法人買賣 (TWSE T86)
- `TaiwanStockShareholding` — 外資持股表
- `TaiwanStockMarginShortSaleSuspension` — 暫停融券賣出 (融券回補日) — TPEX 上櫃
- `TaiwanStockMarginRatio` — 大盤融資維持率
- `TaiwanStockHoldingSharesPer` — 集保戶股權分散表 (TDCC 17 分級)
- `TaiwanStockDisposition` — 公布處置有價證券表
- `TaiwanStockDayTradingFee` — 現股當日沖銷券差借券費率 (TPEX 上櫃)
- `TaiwanStockMonthRevenue` — 月營收表
- `TaiwanStockMarketValue` — 台股市值 — 收盤價 × 已發行股數
- `TaiwanStockMarketValueWeight` — 台股市值占比 — 各股市值占大盤百分比
- `TaiwanMonthlyEconomicIndicator` — 台灣每月景氣對策信號
- `TaiwanStockCompanyIndustry` — 個體公司所屬產業鏈
- `TaiwanFuturesBrokerDaily` — 期貨各券商每日交易 (rolling 1-month window)
- `TaiwanOptionsBrokerDaily` — 選擇權各券商每日交易 (rolling 1-month window)
- `TaiwanFuturesLargeTraders` — 期貨大額交易人未沖銷部位 — 每日 snapshot (TAIFEX 不支援歷史)
- `TaiwanOptionsLargeTraders` — 選擇權大額交易人未沖銷部位 — 每日 snapshot
- `TaiwanFuturesNightInstitutionalInvestors` — 期貨夜盤三大法人買賣
- `TaiwanOptionsNightInstitutionalInvestors` — 選擇權夜盤三大法人買賣
- `TaiwanFuturesSettlement` — 期貨每日結算價 — 從每日 CSV 取最近月份契約
- `TaiwanOptionsSettlement` — 選擇權每日結算價
- `TaiwanFuturesSpread` — 期貨價差行情 — 不同月份契約的價差
- `TaiwanFinancialHoldingsCompany` — 上市金融控股公司資料

### Plus (4)

- `TaiwanStock5SecondsOrderStats` — 每 5 秒委託成交統計 — 大盤匯總 (stock_id=MARKET)
- `TaiwanIndex5Seconds` — 每 5 秒指數 — TAIEX + 32 類股指數
- `TaiwanCBOverview` — 可轉債總覽 — TPEX 全部 412 檔
- `TaiwanFearAndGreedIndex` — 市場恐懼與貪婪指數 (alternative.me 全球情緒，含 8 年歷史)

## Examples

```
curl -H "Authorization: Bearer YOUR_KEY" \
     "https://clarifindata.com/api/v1/data/TaiwanStockPrice?stock_id=2330&start=2026-04-01&end=2026-04-30"
```

```
curl -H "Authorization: Bearer YOUR_KEY" https://clarifindata.com/api/v1/key/info
# {"tier":"free","rate_limit_per_hour":600,"remaining_this_hour":597}
```