# NGUỒN DỮ LIỆU MIỄN PHÍ — XÁC NHẬN & PHÂN LOẠI MÃ GIAO DỊCH
# Free Data Sources — Confirmed & Symbol Classification v4.0

═══════════════════════════════════════════════════════════════════════
## A. BẢNG NGUỒN DỮ LIỆU MIỄN PHÍ (Confirmed Free Sources)
═══════════════════════════════════════════════════════════════════════

| Nguồn        | URL cơ sở                              | API Key? | Giới hạn miễn phí        | Tốt nhất cho              |
|--------------|----------------------------------------|----------|--------------------------|---------------------------|
| Binance      | api.binance.com/api/v3                 | Không    | 1200 req/min             | Crypto OHLCV (tốt nhất)   |
| Bybit V5     | api.bybit.com/v5/market                | Không    | 120 req/min              | Crypto backup             |
| CoinGecko    | api.coingecko.com/api/v3               | Không    | 30 req/min               | Crypto OHLCV + market cap |
| yfinance     | (scrapes finance.yahoo.com)            | Không    | Không giới hạn chính thức| Stocks, ETF, Forex, Chỉ số|
| Finnhub      | finnhub.io/api/v1                      | Có (free)| 60 req/min               | Forex (OANDA), Stock, Crypto|
| Twelvedata   | api.twelvedata.com                     | Có (free)| 800 credits/ngày, 8/phút | Forex, Stock, Crypto      |
| Alpha Vantage| alphavantage.co/query                  | Có (free)| 25 req/ngày              | Forex fallback (hạn chế)  |
| FRED         | fred.stlouisfed.org/graph/fredgraph    | Không    | Không giới hạn           | Macro (lãi suất, DXY...)  |

### Ưu tiên nguồn theo loại tài sản:
- **Crypto**:       Binance → Bybit → CoinGecko → yfinance → Finnhub
- **Forex**:        Twelvedata → Finnhub (OANDA) → yfinance
- **Kim loại**:     yfinance (futures =F) → Twelvedata → Finnhub
- **Năng lượng**:   yfinance (futures =F) → Twelvedata → Finnhub
- **Nông sản**:     yfinance (futures =F) → Twelvedata
- **Chỉ số**:       yfinance (^SYMBOL) → Twelvedata → Finnhub
- **Cổ phiếu Mỹ**:  yfinance → Finnhub → Twelvedata
- **Cổ phiếu VN**:  yfinance (.VN suffix)
- **Trái phiếu**:   yfinance (^TNX, ^TYX...)

═══════════════════════════════════════════════════════════════════════
## B. PHÂN LOẠI MÃ GIAO DỊCH CHUẨN
═══════════════════════════════════════════════════════════════════════

### 1. KIM LOẠI (Metals) — 13 mã
| Mã           | Tên VN              | Ticker yfinance | Nguồn tốt nhất      |
|--------------|---------------------|-----------------|---------------------|
| XAUUSD       | Vàng                | GC=F            | Twelvedata, Finnhub  |
| XAGUSD       | Bạc                 | SI=F            | Twelvedata, Finnhub  |
| XPTUSD       | Bạch kim            | PL=F            | Twelvedata, yfinance |
| XPDUSD       | Palladium           | PA=F            | Twelvedata, yfinance |
| COPPER       | Đồng COMEX          | HG=F            | yfinance, Twelvedata |
| COPPER_LME   | Đồng LME            | HG=F            | Twelvedata           |
| ALUMINUM     | Nhôm COMEX          | ALI=F           | yfinance             |
| ALUMINUM_LME | Nhôm LME            | LMAHDS03        | Twelvedata           |
| NICKEL_LME   | Niken LME           | NI1             | Twelvedata           |
| ZINC_LME     | Kẽm LME             | ZN1             | Twelvedata           |
| IRON_ORE     | Quặng sắt           | TIO=F           | yfinance             |
| STEEL_HRC    | Thép cuộn cán nóng  | HRC=F           | yfinance             |
| LITHIUM      | Lithium (proxy ALB) | ALB             | yfinance             |

### 2. NĂNG LƯỢNG (Energy) — 8 mã
| Mã           | Tên VN              | Ticker yfinance | Ghi chú              |
|--------------|---------------------|-----------------|----------------------|
| WTI          | Dầu thô WTI         | CL=F            | Chuẩn Mỹ             |
| BRENT        | Dầu Brent           | BZ=F            | Chuẩn quốc tế        |
| NATURAL_GAS  | Khí tự nhiên        | NG=F            |                      |
| GASOLINE_RBOB| Xăng RBOB           | RB=F            |                      |
| HEATING_OIL  | Dầu sưởi            | HO=F            |                      |
| LNG          | Khí hoá lỏng proxy  | LNG             | Cổ phiếu Cheniere    |
| COAL         | Than Newcastle      | MTF=F           |                      |
| URANIUM      | Uranium             | UX=F            |                      |

### 3. NÔNG SẢN (Agricultural) — 7 mã
| Mã           | Tên VN              | Ticker yfinance |
|--------------|---------------------|-----------------|
| CORN         | Ngô                 | ZC=F            |
| WHEAT        | Lúa mì              | ZW=F            |
| SOYBEAN      | Đậu tương           | ZS=F            |
| SOYBEAN_OIL  | Dầu đậu tương       | ZL=F            |
| SOYBEAN_MEAL | Khô đậu tương       | ZM=F            |
| RICE         | Gạo thô             | ZR=F            |
| OATS         | Yến mạch            | ZO=F            |

### 4. NGUYÊN LIỆU CÔNG NGHIỆP (Soft Commodities) — 10 mã
| Mã             | Tên VN              | Ticker yfinance |
|----------------|---------------------|-----------------|
| COFFEE_ARABICA | Cà phê Arabica      | KC=F            |
| COFFEE_ROBUSTA | Cà phê Robusta      | RC=F            |
| COCOA          | Ca cao              | CC=F            |
| SUGAR_11       | Đường 11            | SB=F            |
| WHITE_SUGAR    | Đường trắng         | LSW=F           |
| COTTON         | Bông                | CT=F            |
| ORANGE_JUICE   | Nước cam            | OJ=F            |
| LUMBER         | Gỗ xẻ              | LBS=F           |
| RUBBER_RSS3    | Cao su RSS3         | JRU=F           |
| PALM_OIL       | Dầu cọ thô          | FCPO=F          |

### 5. CRYPTO — 25 mã (Top by market cap)
| Mã       | Tên            | Binance      | CoinGecko ID        |
|----------|----------------|--------------|---------------------|
| BTCUSD   | Bitcoin        | BTCUSDT      | bitcoin             |
| ETHUSD   | Ethereum       | ETHUSDT      | ethereum            |
| BNBUSD   | BNB            | BNBUSDT      | binancecoin         |
| SOLUSD   | Solana         | SOLUSDT      | solana              |
| XRPUSD   | Ripple         | XRPUSDT      | ripple              |
| ADAUSD   | Cardano        | ADAUSDT      | cardano             |
| AVAXUSD  | Avalanche      | AVAXUSDT     | avalanche-2         |
| DOTUSD   | Polkadot       | DOTUSDT      | polkadot            |
| MATICUSD | Polygon        | MATICUSDT    | matic-network       |
| LINKUSD  | Chainlink      | LINKUSDT     | chainlink           |
| LTCUSD   | Litecoin       | LTCUSDT      | litecoin            |
| UNIUSD   | Uniswap        | UNIUSDT      | uniswap             |
| ATOMUSD  | Cosmos         | ATOMUSDT     | cosmos              |
| NEARUSD  | NEAR Protocol  | NEARUSDT     | near                |
| APTUSD   | Aptos          | APTUSDT      | aptos               |
| SUIUSD   | Sui            | SUIUSDT      | sui                 |
| ARBUSD   | Arbitrum       | ARBUSDT      | arbitrum            |
| OPUSD    | Optimism       | OPUSDT       | optimism            |
| INJUSD   | Injective      | INJUSDT      | injective-protocol  |
| TONUSD   | Toncoin        | TONUSDT      | the-open-network    |
| TRXUSD   | Tron           | TRXUSDT      | tron                |
| XMRUSD   | Monero         | (Bybit only) | monero              |
| DOGEUSD  | Dogecoin       | DOGEUSDT     | dogecoin            |
| SHIBAUSD | Shiba Inu      | SHIBUSDT     | shiba-inu           |
| PEPE     | PEPE Coin      | PEPEUSDT     | pepe                |

### 6. CẶP TIỀN (Forex) — 19 mã
| Mã       | Tên           | Twelvedata   | Finnhub          | yfinance     |
|----------|---------------|--------------|------------------|--------------|
| DXY      | Chỉ số USD    | —            | —                | DX-Y.NYB     |
| EURUSD   | EUR/USD       | EUR/USD      | OANDA:EUR_USD    | EURUSD=X     |
| GBPUSD   | GBP/USD       | GBP/USD      | OANDA:GBP_USD    | GBPUSD=X     |
| USDJPY   | USD/JPY       | USD/JPY      | OANDA:USD_JPY    | JPY=X        |
| USDCHF   | USD/CHF       | USD/CHF      | OANDA:USD_CHF    | CHF=X        |
| AUDUSD   | AUD/USD       | AUD/USD      | OANDA:AUD_USD    | AUDUSD=X     |
| USDCAD   | USD/CAD       | USD/CAD      | OANDA:USD_CAD    | CAD=X        |
| NZDUSD   | NZD/USD       | NZD/USD      | OANDA:NZD_USD    | NZDUSD=X     |
| GBPJPY   | GBP/JPY       | GBP/JPY      | OANDA:GBP_JPY    | GBPJPY=X     |
| EURJPY   | EUR/JPY       | EUR/JPY      | OANDA:EUR_JPY    | EURJPY=X     |
| EURGBP   | EUR/GBP       | EUR/GBP      | OANDA:EUR_GBP    | EURGBP=X     |
| CADCHF   | CAD/CHF       | CAD/CHF      | OANDA:CAD_CHF    | CADCHF=X     |
| AUDNZD   | AUD/NZD       | AUD/NZD      | OANDA:AUD_NZD    | AUDNZD=X     |
| USDVND   | USD/VND       | —            | —                | VND=X        |
| USDHKD   | USD/HKD       | USD/HKD      | —                | HKD=X        |
| USDSGD   | USD/SGD       | USD/SGD      | —                | SGD=X        |
| USDCNY   | USD/CNY       | USD/CNH      | —                | CNY=X        |
| USDINR   | USD/INR       | —            | —                | INR=X        |
| USDBRL   | USD/BRL       | —            | —                | BRL=X        |

### 7. CHỈ SỐ (Stock Indices) — 20 mã
| Mã         | Tên                  | yfinance   | Ghi chú         |
|------------|----------------------|------------|-----------------|
| SP500      | S&P 500              | ^GSPC      | Chuẩn Mỹ        |
| NASDAQ     | Nasdaq Composite     | ^IXIC      |                 |
| NASDAQ100  | Nasdaq 100           | ^NDX       |                 |
| DOW30      | Dow Jones 30         | ^DJI       |                 |
| RUSSELL2000| Russell 2000         | ^RUT       | Small-cap Mỹ   |
| VIX        | VIX Fear Index       | ^VIX       |                 |
| VNINDEX    | VN-Index (HOSE)      | ^VNINDEX   | Việt Nam        |
| HNX30      | HNX 30               | ^HNX30     | Việt Nam        |
| UK100      | FTSE 100             | ^FTSE      | Anh             |
| DAX40      | DAX 40               | ^GDAXI     | Đức             |
| EU50       | Euro Stoxx 50        | ^STOXX50E  | Châu Âu         |
| CAC40      | CAC 40               | ^FCHI      | Pháp            |
| NIKKEI225  | Nikkei 225           | ^N225      | Nhật Bản        |
| HSI        | Hang Seng            | ^HSI       | Hong Kong       |
| SSE50      | SSE 50               | 000016.SS  | Trung Quốc      |
| CSI300     | CSI 300              | 000300.SS  | Trung Quốc      |
| ASX200     | ASX 200              | ^AXJO      | Úc              |
| SENSEX     | BSE Sensex           | ^BSESN     | Ấn Độ           |
| KOSPI      | KOSPI                | ^KS11      | Hàn Quốc        |
| SGX        | Straits Times        | ^STI       | Singapore       |

### 8. CỔ PHIẾU MỸ (US Stocks) — 21 mã
AAPL, MSFT, NVDA, GOOGL, AMZN, META, TSLA, AVGO, JPM, V, MA,
XOM, WMT, BAC, GS, AMD, INTC, NFLX, DIS, COIN, MSTR
→ Tất cả dùng yfinance + Finnhub + Twelvedata (ticker trực tiếp)

### 9. CỔ PHIẾU VIỆT NAM (VN Stocks) — 25 mã (yfinance .VN suffix)
Ngân hàng: VCB, BID, CTG, TCB, MBB, VPB, ACB, HDB, SHB, STB
Công nghệ: FPT
Bất động sản: VIC, VHM
FMCG: VNM, MSN, SAB
Năng lượng/CN: GAS, PLX, POW, HPG, DGC
Tiêu dùng: MWG
Chứng khoán: SSI, VND, HCM

### 10. TRÁI PHIẾU & LÃI SUẤT (Bonds & Rates) — 5 mã
| Mã     | Tên                  | yfinance     | Ghi chú                |
|--------|----------------------|--------------|------------------------|
| US10Y  | Trái phiếu Mỹ 10 năm | ^TNX        | Chuẩn lãi suất toàn cầu|
| US02Y  | Trái phiếu Mỹ 2 năm  | ^IRX        |                        |
| US30Y  | Trái phiếu Mỹ 30 năm | ^TYX        |                        |
| DE10Y  | Bund Đức 10 năm      | ^DE10YT=RR  |                        |
| JP10Y  | JGB Nhật 10 năm      | ^JP10YT=RR  |                        |

═══════════════════════════════════════════════════════════════════════
## C. API ENDPOINTS v4.0
═══════════════════════════════════════════════════════════════════════

### Dữ liệu lịch sử
GET  /api/symbols               → Danh sách tất cả mã (có thể lọc theo category)
GET  /api/search?q=gold         → Tìm kiếm mờ (fuzzy search)
GET  /api/historical/{symbol}   → Nến OHLCV (interval, limit)
GET  /api/indicators/{symbol}   → Chỉ báo kỹ thuật (RSI, MACD, BB, EMA, ATR)

### Giá thực tế
GET  /api/ticker/{symbol}       → Giá cuối + 24h stats
POST /api/watchlist/tickers     → Batch ticker cho danh mục
GET  /api/crypto/market         → Top N crypto theo vốn hoá (CoinGecko)
WS   /ws/price/{symbol}         → WebSocket stream giá thực tế (5s)

### AI Forecast
GET  /api/forecast/{symbol}     → Dự báo Kronos (horizon, quantiles 10/50/90)

### Thị trường
GET  /api/market-status         → Trạng thái mở/đóng cửa các sàn thế giới

### Cache & Admin
POST   /api/switch              → Xoá cache khi đổi symbol/interval
DELETE /api/cache/{sym}/{iv}    → Xoá cache cụ thể
DELETE /api/cache               → Xoá tất cả cache
GET    /api/cache/stats         → Thống kê cache
GET    /api/health              → Trạng thái server

═══════════════════════════════════════════════════════════════════════
## D. CÀI ĐẶT & CHẠY
═══════════════════════════════════════════════════════════════════════

# 1. Cài đặt dependencies
pip install -r requirements.txt

# 2. Cài pytz (cần cho market-status)
pip install pytz

# 3. Chạy server
uvicorn main:app --host 0.0.0.0 --port 8000 --reload

# 4. Xem API docs
http://localhost:8000/docs

# 5. Kiểm tra health
curl http://localhost:8000/api/health

# 6. Test lấy giá vàng
curl "http://localhost:8000/api/historical/XAUUSD?interval=1h&limit=100"

# 7. Test chỉ báo kỹ thuật BTC
curl "http://localhost:8000/api/indicators/BTCUSD?interval=4h"

# 8. Test thị trường đang mở
curl http://localhost:8000/api/market-status