# Quant ChaoGu

> Lean Taiwan-stock market-data API. Subscriptions for humans, x402 micropayments for AI agents.

## Authentication

Header `X-API-Key: <key>` or `Authorization: Bearer <key>`.
Public demo keys (intentionally in our repo):
- Free:  `qcg_demo_free_0001`
- Lite:  `qcg_demo_lite_0002`
- Plus:  `qcg_demo_plus_0003`

## Endpoints

- `GET /v1/data` — list datasets (no auth)
- `GET /v1/data/{dataset}` — query a dataset; params: stock_id, start, end, limit (≤10000)
- `POST /v1/ask` — natural-language → SQL via DeepSeek (Plus tier only)
- `GET /v1/agent/{dataset}` — same data, paid per-call via x402/USDC on Base Sepolia
- `GET /llms.txt` — this file
- `GET /healthz` — liveness

## Rate limits (per hour)

- Free  600   ·  Lite  3 000   ·  Plus  10 000
- Headers `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Tier`

## x402 payments

Unauthenticated `GET /v1/agent/{dataset}` returns:

```
HTTP/1.1 402 Payment Required
payment-required: <base64 JSON>
```

Decoded payload describes `scheme=exact`, `network=eip155:84532` (Base Sepolia),
USDC contract, atomic-unit amount (1000 = $0.001), and pay-to address.
Sign the EIP-712 intent with your wallet, retry with `X-PAYMENT: <signed>`.

## Datasets

### `TaiwanStockPrice` (free)
個股日 K (TWSE STOCK_DAY)
- table: `taiwan_stock_price`
- columns: `stock_id`, `trade_date`, `open`, `high`, `low`, `close`, `volume`, `turnover`, `trade_count`, `spread`

### `TaiwanStockPriceAdj` (lite)
還原股價 — 除權息調整
- table: `taiwan_stock_price_adj`
- columns: `stock_id`, `trade_date`, `open_adj`, `high_adj`, `low_adj`, `close_adj`, `adj_factor`

### `TaiwanStockWeekPrice` (lite)
台股週 K — 由日 K 聚合
- table: `taiwan_stock_week_price`
- columns: `stock_id`, `week_start`, `week_end`, `open`, `high`, `low`, `close`, `volume`, `turnover`

### `TaiwanStockMonthPrice` (lite)
台股月 K — 由日 K 聚合
- table: `taiwan_stock_month_price`
- columns: `stock_id`, `month_start`, `open`, `high`, `low`, `close`, `volume`, `turnover`

### `TaiwanStockInstitutionalInvestorsBuySell` (free)
個股三大法人買賣 (TWSE T86)
- table: `taiwan_stock_institutional_investors_buy_sell`
- columns: `stock_id`, `trade_date`, `foreign_buy`, `foreign_sell`, `foreign_net`, `trust_buy`, `trust_sell`, `trust_net`, `dealer_buy`, `dealer_sell`, `dealer_net`, `total_net`

## Source

Open-source MIT. Code: https://github.com/<TBD>/quantchaogu