settfex 0.6.0__tar.gz → 0.7.0__tar.gz

{settfex-0.6.0 → settfex-0.7.0}/.gitignore

@@ -197,6 +197,6 @@ config/*.yml
 !config/*.default.yml
 
 # AI Assistant and Meta Files
-CLAUDE.md
+# CLAUDE.md is tracked (project instructions for AI assistants); .claude/ and scripts/ stay local.
 .claude/
 scripts/

{settfex-0.6.0 → settfex-0.7.0}/CHANGELOG.md

@@ -7,6 +7,26 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.7.0] - 2026-06-21
+
+### Added
+
+- **Latest traded price for SET stocks** — on top of the existing chart-quotation service, a
+  first-class way to get the most recent *traded* price relative to now. The SET intraday feed
+  pre-populates the rest of the session with null/no-trade buckets; these are excluded
+  automatically.
+  - `get_latest_price(symbol, period="1D", accumulated=False, as_of=None) -> Quotation | None` —
+    top-level convenience returning the latest traded quotation (time, price, volume, change), or
+    `None` if nothing has traded yet.
+  - `ChartQuotation.get_latest_quotation(as_of=None) -> Quotation | None` and
+    `ChartQuotation.get_latest_price(as_of=None) -> float | None` (scalar, falls back to `prior`) —
+    pure, timezone-safe selection in Asia/Bangkok; `as_of` defaults to now (naive values are
+    treated as Bangkok local time).
+  - `Stock.get_latest_price(period="1D", accumulated=False, as_of=None)` on the unified Stock class.
+  - Hyphenated warrant symbols (e.g. `JAS-W4`) are preserved.
+  - The chart-quotation models, service, and `get_chart_quotation` are now also exported from
+    `settfex.services.set` (previously only from `settfex.services.set.stock`).
+
 ## [0.6.0] - 2026-06-19
 
 ### Added

settfex-0.7.0/CLAUDE.md

@@ -0,0 +1,234 @@
+# CLAUDE.md - AI Assistant Context
+
+Essential context and guidelines for AI assistants working on the settfex project.
+
+## Project Overview
+
+**settfex** is a Python library that fetches real-time and historical data from:
+- **SET** (Stock Exchange of Thailand)
+- **TFEX** (Thailand Futures Exchange)
+
+Published on PyPI, targeting Python 3.11+ with modern async patterns.
+
+## Project Structure
+
+```
+settfex/
+├── settfex/                    # Main package
+│   ├── services/              # Business logic and API integrations
+│   │   ├── set/              # SET-specific services (11 services)
+│   │   │   ├── constants.py, list.py
+│   │   │   └── stock/        # Stock services: highlight_data, profile_stock,
+│   │   │                     #   profile_company, corporate_action, shareholder,
+│   │   │                     #   nvdr_holder, board_of_director, trading_stat,
+│   │   │                     #   price_performance, financial/, stock.py, utils.py
+│   │   └── tfex/             # TFEX services: list.py, trading_statistics.py
+│   └── utils/                # http.py, data_fetcher.py, session_manager.py,
+│                             #   session_cache.py, logging.py
+├── tests/                     # Mirror of settfex/ with test_ prefix
+├── docs/                      # Service docs, guides, solutions
+├── examples/                  # 13 Jupyter notebooks (11 SET + 2 TFEX)
+├── scripts/                   # Verification scripts per service
+├── .github/                   # CI and agent instructions
+├── pyproject.toml             # uv-based config
+└── README.md
+```
+
+## Architecture Principles
+
+1. **Modular Design**: Clear separation between SET and TFEX services
+2. **Service Layer**: All external API interactions encapsulated in `services/`
+3. **Utilities**: Reusable helpers in `utils/` for cross-cutting concerns
+4. **Type Safety**: Full type hints and Pydantic validation throughout
+5. **Modern Python**: Python 3.11+ with async/await patterns
+6. **Testing**: Comprehensive pytest coverage (>80% target)
+7. **Documentation**: Maintained docs for all public APIs
+
+## Development Guidelines
+
+### Code Style
+- PEP 8 with 100-char line length; Ruff linting; mypy strict mode
+- All functions must have type hints
+
+### Dependencies
+- **curl_cffi**: Async HTTP with browser impersonation (replaced httpx 2025-10-01)
+- **loguru**: Structured logging with colored output, rotation, compression (replaced stdlib logging 2025-10-01)
+- **pydantic**: Runtime validation and settings management
+- Minimize external dependencies
+
+### Testing
+- Write tests for all new features; mock external API calls
+- Use pytest fixtures in `conftest.py` for shared setup
+- Maintain >80% coverage
+
+### Documentation
+- Update docs when adding features; include docstrings for all public APIs
+- Keep Jupyter notebook examples up-to-date
+
+## Common Tasks
+
+### Adding a New Service (SET or TFEX)
+1. Create module in `settfex/services/{set,tfex}/`
+2. Add tests in `tests/services/{set,tfex}/`
+3. Update the appropriate `__init__.py` to export the service
+4. Document with docstrings + create verification script in `scripts/settfex/services/`
+5. Add Jupyter notebook example in `examples/`
+
+### Adding Utility Functions
+1. Add to appropriate module in `settfex/utils/` or create new one
+2. Add tests in `tests/utils/`; ensure utilities are generic and reusable
+
+## Service Design Patterns (Must Follow)
+
+Every service follows this consistent pattern:
+- **Pydantic models** for all data with full type annotations
+- **Two fetch methods**: `fetch_*()` returns Pydantic models; `fetch_*_raw()` returns raw dicts
+- **Convenience function**: `get_*()` top-level function for one-line access
+- **Dual language**: `en`/`th` support via `normalize_language()` (accepts: en/eng/english, th/tha/thai)
+- **Symbol normalization**: Auto-uppercase via `normalize_symbol()`
+- **SessionManager**: All cookie/bot-detection handled automatically (no manual cookie params)
+- **Async-first**: All I/O uses async/await via `AsyncDataFetcher`
+- **Bot bypass**: Symbol-specific referer header + SessionManager cookies (Incapsula bypass)
+
+Typical usage:
+```python
+from settfex.services.set import Stock, get_highlight_data, get_stock_list
+
+stock = Stock("CPALL")
+data = await stock.get_highlight_data()    # via unified Stock class
+data = await get_highlight_data("CPALL")   # or convenience function
+all_stocks = await get_stock_list()        # no cookie params needed
+```
+
+## Services Inventory (16 total)
+
+### SET Services (14)
+
+| # | Service | Module | Endpoint Pattern | Key Data |
+|---|---|---|---|---|
+| 1 | Stock List | `list.py` | `/api/set/stock/list` | All SET/MAI stocks, filter by market/industry/symbol |
+| 2 | Highlight Data | `stock/highlight_data.py` | `/api/set/stock/{sym}/highlight-data` | P/E, P/B, market cap, beta, dividends, 52-wk range, NVDR |
+| 3 | Stock Profile | `stock/profile_stock.py` | `/api/set/stock/{sym}/profile` | Listing details, IPO, sector, foreign limits, ISIN, warrants |
+| 4 | Company Profile | `stock/profile_company.py` | `/api/set/company/{sym}/profile` | ESG rating, CG score, auditors, management, capital structure |
+| 5 | Corporate Actions | `stock/corporate_action.py` | `/api/set/stock/{sym}/corporate-action` | Dividends (XD), meetings (XM/AGM/EGM), payment dates |
+| 6 | Shareholders | `stock/shareholder.py` | `/api/set/stock/{sym}/shareholder` | Major holders, free float %, ownership distribution |
+| 7 | NVDR Holders | `stock/nvdr_holder.py` | `/api/set/stock/{sym}/nvdr-holder` | NVDR ownership, Thai vs foreign holders |
+| 8 | Board of Directors | `stock/board_of_director.py` | `/api/set/company/{sym}/board-of-director` | Directors, positions (Chairman, CEO, Independent) |
+| 9 | Trading Statistics | `stock/trading_stat.py` | `/api/set/factsheet/{sym}/trading-stat` | 30+ fields: price/volume/valuation/beta, 5 periods (YTD-1Y) |
+| 10 | Price Performance | `stock/price_performance.py` | `/api/set/factsheet/{sym}/price-performance` | Stock vs sector vs market (5D/1M/3M/6M/YTD), P/E, P/B |
+| 11 | Financial Statements | `stock/financial/financial.py` | `/api/set/factsheet/{sym}/financialstatement` | Balance sheet, income, cash flow (multi-period, en/th) |
+| 12 | Earnings Call (Opportunity Day) | `earnings_call.py` | `POST api.lcp.setgroup.or.th/.../investor/search/archive` (+ `GET /investor/vdo/{id}`, `/investor/filter/*`) | OPPDAY calendar (symbol, company, date, clip duration, YouTube URL); concurrent `fetch_all`/`get_all_earnings_calls` (+ optional `tqdm` progress); detail-by-id (`get_earnings_call_detail`); 7 filter helpers; pandas `to_dataframe()`; **Thai YouTube transcripts** for AI (`fetch_transcripts` / `get_earnings_call_transcript` / `fetch_youtube_transcript`, `EarningsCallItem.transcript`); stateless host (no SessionManager); optional extras: `dataframe` (pandas) / `progress` (tqdm) / `transcript` (youtube-transcript-api) |
+| 13 | Chart Quotation / Latest Price | `stock/chart_quotation.py` | `/api/set/stock/{sym}/chart-quotation` | Intraday/historical per-minute series (price/volume/value/%chg, intermissions, prior close); **latest *traded* price relative to now** — `get_latest_price()` (→ `Quotation`), model `get_latest_quotation()`/`get_latest_price()` (→ float, `prior` fallback); skips null future/lunch/no-trade buckets; Asia/Bangkok tz-safe `as_of`; hyphen-safe symbols (`JAS-W4`) |
+| 14 | Latest Historical Trading | `stock/latest_historical_trading.py` | `/api/set/stock/{sym}/latest-historical-trading` | Latest trading-day summary: OHLCV, change/%change, and valuation metrics |
+
+### TFEX Services (2)
+
+| # | Service | Module | Endpoint Pattern | Key Data |
+|---|---|---|---|---|
+| 1 | Series List | `list.py` | `/api/set/tfex/series/list` | Futures/options, 8 filter methods, contract details |
+| 2 | Trading Statistics | `trading_statistics.py` | `/api/set/tfex/series/{sym}/trading-statistics` | Settlement, margin (IM/MM), theoretical price, days to maturity |
+
+### Unified Stock Class (`stock/stock.py`)
+Single entry point for SET stock data — initialize with symbol, access all services via lazy-init properties:
+```python
+stock = Stock("CPALL")
+highlight = await stock.get_highlight_data()
+profile = await stock.get_profile()
+financials = await stock.get_balance_sheet()
+latest = await stock.get_latest_price()    # latest traded price vs now
+# ... all stock services accessible
+```
+
+## API Design Principles
+
+1. **Consistency**: SET and TFEX services follow identical patterns
+2. **Simplicity**: Simple, intuitive APIs; one-line convenience functions
+3. **Async-first**: async/await for all I/O operations
+4. **Error Handling**: Clear, informative error messages
+5. **Validation**: Pydantic models for all inputs and outputs
+6. **Documentation**: All public APIs well-documented
+
+## Key Technical Decisions
+
+| Area | Choice | Reason |
+|---|---|---|
+| HTTP client | `curl_cffi` | Browser impersonation for bot detection bypass |
+| Logging | `loguru` | Colored output, auto-rotation, better exception traces |
+| Validation | Pydantic | Full type safety with runtime validation |
+| Async | `asyncio.to_thread` | Wraps sync curl_cffi for async compatibility |
+| Session mgmt | `SessionManager` | 25x speedup via cookie warming + caching |
+| Build | `uv` (pyproject.toml) | Fast dependency resolution |
+| Lint | Ruff + mypy strict | Modern, fast tooling |
+
+## Target Users
+
+- Python developers building trading applications
+- Financial analysts needing Thailand market data
+- Quantitative researchers and data scientists
+- Automated trading system developers
+
+## Important Notes
+
+- This library is **not officially affiliated** with SET or TFEX
+- Always respect API rate limits and terms of service
+- Handle sensitive data (API keys, credentials) securely
+- Never commit credentials or API keys to version control
+
+## Recent Change History (Condensed)
+
+### 2025-10-05
+- **Jupyter Examples**: 13 notebooks covering all services with beginner guides, professional use cases, and CSV/pandas export
+- **TFEX Trading Statistics**: Settlement prices, margin (IM/MM), days to maturity, theoretical pricing
+- **TFEX Series List**: Complete futures/options discovery with 8 filter methods
+- **Financial Service**: Balance sheet, income statement, cash flow — multi-period with en/th support, 98% test coverage
+
+### 2025-10-04
+- **Price Performance**: Stock vs sector vs market across 5 periods (5D–YTD), P/E, P/B, turnover
+- **Trading Statistics (SET)**: 30+ fields across YTD/1M/3M/6M/1Y periods — price, volume, valuation, beta
+
+### 2025-10-03
+- **Board of Directors**: Director names, positions, en/th support
+- **NVDR Holders**: NVDR ownership data with Thai/foreign holder identification
+- **Corporate Actions**: Dividends (XD) and meetings (XM) with full detail
+- **Company Profile**: ESG ratings, CG scores, management, auditors, capital structure
+- **Shareholders**: Major holders, free float, ownership distribution
+- **Refactoring**: Removed legacy cookie generation (~200 lines); SessionManager now handles all bot detection
+
+### 2025-10-02
+- **Stock Profile**: 30+ fields — listing, IPO, sector, foreign limits, ISIN, warrants
+- **Highlight Data**: P/E, P/B, market cap, dividends, NVDR, 52-week range
+- **Unified Stock class**: Single entry point for all stock services with lazy init
+- **Stock utilities**: `normalize_symbol()`, `normalize_language()` shared across all services
+
+### 2025-10-01
+- **Stock List Service**: Full SET/MAI stock list with market/industry/symbol filtering
+- **AsyncDataFetcher**: Core HTTP client with Unicode/Thai support, retry logic, bot impersonation
+- **Migration**: httpx → curl_cffi (bot bypass), stdlib logging → loguru
+- Established the service architecture pattern used by all subsequent services
+
+## Future Enhancements (Ideas)
+
+- WebSocket support for real-time streaming
+- Data caching mechanisms, rate limiting
+- CLI tool for quick data queries
+- pandas/polars integration
+- Historical data export (CSV, Parquet)
+
+## When Working on This Project
+
+1. **Read First**: Check existing code patterns before implementing
+2. **Test**: Write tests before or alongside code
+3. **Document**: Update docs when adding features
+4. **Consistency**: Follow existing patterns and naming conventions
+5. **Type Safety**: Always use type hints
+6. **Ask Questions**: If unclear about architecture, ask for clarification
+
+## Contact & Resources
+
+- Documentation: `docs/` directory
+- Issues: GitHub Issues
+- License: MIT
+
+---
+
+*This file should be kept up-to-date as the project evolves.*

{settfex-0.6.0 → settfex-0.7.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: settfex
-Version: 0.6.0
+Version: 0.7.0
 Summary: Async Python library for fetching real-time and historical data from the Stock Exchange of Thailand (SET) and Thailand Futures Exchange (TFEX)
 Project-URL: Homepage, https://github.com/lumduan/settfex
 Project-URL: Documentation, https://github.com/lumduan/settfex#readme
@@ -101,6 +101,8 @@ All examples include beginner explanations, professional trading use cases, and
 9. **[Trading Statistics](examples/set/09_trading_statistics.ipynb)** - Multi-period performance and volatility
 10. **[Price Performance](examples/set/10_price_performance.ipynb)** - Sector comparison and alpha calculation
 11. **[Financial Statements](examples/set/11_financial.ipynb)** - Balance sheet, income, cash flow analysis
+12. **[Earnings Call (Opportunity Day)](examples/set/12_earnings_call.ipynb)** - OPPDAY calendar, YouTube links, Thai transcripts for AI
+13. **[Chart Quotation & Latest Price](examples/set/13_chart_quotation.ipynb)** - Intraday series and the latest traded price relative to now
 
 ### 📈 TFEX Examples (Thailand Futures Exchange)
 
@@ -128,7 +130,7 @@ Want to dig deeper? Check out our detailed guides:
 - **[Trading Statistics Service](docs/settfex/services/set/trading_stat.md)** - Historical trading performance and metrics
 - **[Price Performance Service](docs/settfex/services/set/price_performance.md)** - Stock, sector, and market price performance comparison
 - **[Financial Service](docs/settfex/services/set/financial.md)** - Balance sheet, income statement, and cash flow data
-- **[Chart Quotation Service](docs/settfex/services/set/chart_quotation.md)** - Intraday and historical price chart data
+- **[Chart Quotation Service](docs/settfex/services/set/chart_quotation.md)** - Intraday/historical price chart series, plus the latest *traded* price relative to now
 - **[Latest Historical Trading Service](docs/settfex/services/set/latest_historical_trading.md)** - Latest trading day summary with OHLCV and valuation metrics
 - **[Earnings Call (Opportunity Day) Service](docs/settfex/services/set/earnings_call.md)** - OPPDAY earnings-call calendar with YouTube links, as models or a DataFrame
 
@@ -357,6 +359,27 @@ print(f"Market ({data.market.symbol}): {data.market.ytd_percent_change:+.2f}%")
 
 ---
 
+#### ⏱️ Get the Latest Traded Price (Intraday)
+
+Fetch the intraday chart-quotation series, or jump straight to the latest *traded* price relative to now (the null future/lunch/no-trade buckets are excluded automatically):
+
+```python
+from settfex.services.set import get_latest_price, get_chart_quotation
+
+# The latest TRADED quotation right now (or None if nothing has traded yet)
+quote = await get_latest_price("CPALL")
+if quote:
+    print(f"{quote.local_datetime}: {quote.price} (vol {quote.volume:,.0f})")
+
+# Or work with the full series; the model also exposes a prior-fallback scalar
+data = await get_chart_quotation("CPALL", period="1D")
+print(f"Prior close: {data.prior}, latest price: {data.get_latest_price()}")
+```
+
+**👉 [Learn more about Chart Quotation & Latest Price](docs/settfex/services/set/chart_quotation.md)**
+
+---
+
 #### 💰 Get Financial Statements
 
 Fetch comprehensive financial data including balance sheet, income statement, and cash flow:
@@ -458,6 +481,12 @@ await fetch_transcripts(hann.items)               # fills item.transcript (Thai)
 text = await get_earnings_call_transcript(6319)   # …or one presentation's transcript by id
 ```
 
+> ⚠️ **Transcripts & YouTube limits.** YouTube rate-limits / IP-blocks aggressively (especially
+> from cloud servers), so transcript fetching is built for a **filtered** set (a company /
+> quarter) — not the full ~9,520-video archive — and defaults to low concurrency (3). A
+> blocked/missing/disabled transcript simply comes back as `None`; if your host IP is blocked,
+> pass `proxies={"http": ..., "https": ...}`. Results can vary by IP.
+
 **👉 [Learn more about the Earnings Call Service](docs/settfex/services/set/earnings_call.md)**
 
 ---

{settfex-0.6.0 → settfex-0.7.0}/README.md

@@ -54,6 +54,8 @@ All examples include beginner explanations, professional trading use cases, and
 9. **[Trading Statistics](examples/set/09_trading_statistics.ipynb)** - Multi-period performance and volatility
 10. **[Price Performance](examples/set/10_price_performance.ipynb)** - Sector comparison and alpha calculation
 11. **[Financial Statements](examples/set/11_financial.ipynb)** - Balance sheet, income, cash flow analysis
+12. **[Earnings Call (Opportunity Day)](examples/set/12_earnings_call.ipynb)** - OPPDAY calendar, YouTube links, Thai transcripts for AI
+13. **[Chart Quotation & Latest Price](examples/set/13_chart_quotation.ipynb)** - Intraday series and the latest traded price relative to now
 
 ### 📈 TFEX Examples (Thailand Futures Exchange)
 
@@ -81,7 +83,7 @@ Want to dig deeper? Check out our detailed guides:
 - **[Trading Statistics Service](docs/settfex/services/set/trading_stat.md)** - Historical trading performance and metrics
 - **[Price Performance Service](docs/settfex/services/set/price_performance.md)** - Stock, sector, and market price performance comparison
 - **[Financial Service](docs/settfex/services/set/financial.md)** - Balance sheet, income statement, and cash flow data
-- **[Chart Quotation Service](docs/settfex/services/set/chart_quotation.md)** - Intraday and historical price chart data
+- **[Chart Quotation Service](docs/settfex/services/set/chart_quotation.md)** - Intraday/historical price chart series, plus the latest *traded* price relative to now
 - **[Latest Historical Trading Service](docs/settfex/services/set/latest_historical_trading.md)** - Latest trading day summary with OHLCV and valuation metrics
 - **[Earnings Call (Opportunity Day) Service](docs/settfex/services/set/earnings_call.md)** - OPPDAY earnings-call calendar with YouTube links, as models or a DataFrame
 
@@ -310,6 +312,27 @@ print(f"Market ({data.market.symbol}): {data.market.ytd_percent_change:+.2f}%")
 
 ---
 
+#### ⏱️ Get the Latest Traded Price (Intraday)
+
+Fetch the intraday chart-quotation series, or jump straight to the latest *traded* price relative to now (the null future/lunch/no-trade buckets are excluded automatically):
+
+```python
+from settfex.services.set import get_latest_price, get_chart_quotation
+
+# The latest TRADED quotation right now (or None if nothing has traded yet)
+quote = await get_latest_price("CPALL")
+if quote:
+    print(f"{quote.local_datetime}: {quote.price} (vol {quote.volume:,.0f})")
+
+# Or work with the full series; the model also exposes a prior-fallback scalar
+data = await get_chart_quotation("CPALL", period="1D")
+print(f"Prior close: {data.prior}, latest price: {data.get_latest_price()}")
+```
+
+**👉 [Learn more about Chart Quotation & Latest Price](docs/settfex/services/set/chart_quotation.md)**
+
+---
+
 #### 💰 Get Financial Statements
 
 Fetch comprehensive financial data including balance sheet, income statement, and cash flow:
@@ -411,6 +434,12 @@ await fetch_transcripts(hann.items)               # fills item.transcript (Thai)
 text = await get_earnings_call_transcript(6319)   # …or one presentation's transcript by id
 ```
 
+> ⚠️ **Transcripts & YouTube limits.** YouTube rate-limits / IP-blocks aggressively (especially
+> from cloud servers), so transcript fetching is built for a **filtered** set (a company /
+> quarter) — not the full ~9,520-video archive — and defaults to low concurrency (3). A
+> blocked/missing/disabled transcript simply comes back as `None`; if your host IP is blocked,
+> pass `proxies={"http": ..., "https": ...}`. Results can vary by IP.
+
 **👉 [Learn more about the Earnings Call Service](docs/settfex/services/set/earnings_call.md)**
 
 ---

settfex-0.7.0/docs/settfex/services/set/chart_quotation.md

@@ -0,0 +1,191 @@
+# Stock Chart Quotation Service
+
+## Overview
+
+The Stock Chart Quotation Service fetches the **intraday (and historical) chart-quotation feed**
+for an individual SET stock symbol — the per-interval price / volume / value / change series shown
+on the SET price chart. On top of that raw series it provides a first-class way to retrieve the
+**latest *traded* price relative to now**, correctly excluding the null-valued buckets the API
+pre-populates for the remainder of the trading day.
+
+Endpoint: `GET /api/set/stock/{symbol}/chart-quotation?period=1D&accumulated=false`
+
+## Key Features
+
+- **Intraday + historical** — `period` of `1D`, `5D`, `1M`, `3M`, `6M`, `1Y`, `3Y`, `5Y`, `MAX`.
+- **Latest traded price vs. now** — `get_latest_price()` returns the most recent quotation that
+  actually traded (non-null `volume`), skipping future / lunch-break / no-trade buckets.
+- **Timezone-correct** — quotation timestamps are tz-aware (`+07:00`); `as_of` inputs (naive or any
+  zone) are normalized to Asia/Bangkok before comparison.
+- **Hyphen-safe symbols** — warrant symbols like `JAS-W4` are preserved (only upper-cased/trimmed).
+- **Type-safe** — full Pydantic models with camelCase→snake_case aliases.
+- **Bot-detection handled** — `SessionManager` warms cookies and builds the symbol-specific referer
+  automatically (Incapsula bypass); no manual cookie params.
+
+## Installation
+
+```bash
+pip install settfex
+```
+
+## Quick Start
+
+### Latest traded price (the headline capability)
+
+```python
+import asyncio
+from settfex.services.set import get_latest_price
+
+async def main():
+    quotation = await get_latest_price("CPALL")        # latest TRADED point, relative to now
+    if quotation:
+        print(f"{quotation.local_datetime}: {quotation.price} (vol {quotation.volume})")
+    else:
+        print("Nothing has traded yet today.")
+
+asyncio.run(main())
+```
+
+### Using the Stock class
+
+```python
+from settfex.services.set import Stock
+
+stock = Stock("CPALL")
+data = await stock.get_chart_quotation(period="1D")    # full ChartQuotation series
+latest = await stock.get_latest_price()                # latest traded Quotation (or None)
+```
+
+### Using the convenience function
+
+```python
+from settfex.services.set import get_chart_quotation
+
+data = await get_chart_quotation("JAS-W4", period="1D")  # hyphenated warrant symbol is fine
+print(f"Prior close: {data.prior}, points: {len(data.quotations)}")
+print(f"Latest price (scalar, prior-fallback): {data.get_latest_price()}")
+```
+
+### Using the service class
+
+```python
+from settfex.services.set.stock import ChartQuotationService
+
+service = ChartQuotationService()
+data = await service.fetch_chart_quotation("CPALL", period="1D", accumulated=False)
+raw = await service.fetch_chart_quotation_raw("CPALL")   # unvalidated dict
+```
+
+## Latest-price selection rule
+
+`ChartQuotation.get_latest_quotation(as_of=None)` returns the quotation with the **greatest
+timestamp that is `<= as_of` and has a non-null `volume`** — i.e. the latest minute that actually
+traded. This matters because the API returns one bucket per minute for the **whole session up to
+end of day**; minutes that are in the future, fall in the lunch `intermission`, or simply had no
+trade carry `volume = null` (the `price` may still be carried forward).
+
+- **`as_of`** defaults to **now in `Asia/Bangkok`**. A naive `as_of` is treated as Bangkok local
+  time; an aware `as_of` (e.g. UTC) is converted. Naive and aware datetimes are never compared
+  directly — both sides are normalized to Bangkok first.
+- **`get_latest_price(as_of=None)`** (on the model) returns that quotation's `price`, **falling
+  back to `prior`** (the previous session's close) when nothing has traded yet, or `None` if
+  `prior` is also unavailable.
+- **Top-level `get_latest_price(symbol, …)`** returns the full **`Quotation`** object (time, price,
+  volume, change), or `None` — a single request, an O(n) scan, no re-fetching.
+
+| Situation | `get_latest_quotation` | `model.get_latest_price` |
+|---|---|---|
+| Mid-session, after trades | latest traded `Quotation` | its `price` |
+| Before the open / all-null series | `None` | `prior` (fallback) |
+| `as_of` inside the lunch break | last morning trade | its `price` |
+| Empty series, `prior` set | `None` | `prior` |
+| Empty series, `prior` is `None` | `None` | `None` |
+
+## API Reference
+
+### Models
+
+#### `Quotation`
+
+| Field | Type | JSON alias | Description |
+|-------|------|-----------|-------------|
+| `quote_datetime` | `datetime` | `datetime` | Timestamp, timezone-aware (`+07:00`) |
+| `local_datetime` | `datetime` | `localDatetime` | Same instant, naive Bangkok local time |
+| `price` | `float \| None` | `price` | Trade price (may be carried forward on no-trade) |
+| `volume` | `float \| None` | `volume` | Trade volume (shares); `None` = no trade this bucket |
+| `value` | `float \| None` | `value` | Trade value (THB) |
+| `change` | `float \| None` | `change` | Price change from prior close |
+| `percent_change` | `float \| None` | `percentChange` | Percentage change from prior close |
+
+#### `Intermission`
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `begin` | `datetime` | Intermission start (e.g. lunch break), naive Bangkok |
+| `end` | `datetime` | Intermission end, naive Bangkok |
+
+#### `ChartQuotation`
+
+| Field / Method | Type | Description |
+|----------------|------|-------------|
+| `prior` | `float \| None` | Prior trading day's close |
+| `intermissions` | `list[Intermission]` | Trading intermission periods |
+| `quotations` | `list[Quotation]` | Per-interval quotation points |
+| `get_latest_quotation(as_of=None)` | `Quotation \| None` | Latest *traded* quotation at/before `as_of` |
+| `get_latest_price(as_of=None)` | `float \| None` | Latest traded price, falling back to `prior` |
+
+### Service Class — `ChartQuotationService`
+
+| Method | Returns | Description |
+|--------|---------|-------------|
+| `fetch_chart_quotation(symbol, period="1D", accumulated=False)` | `ChartQuotation` | Validated model |
+| `fetch_chart_quotation_raw(symbol, period="1D", accumulated=False)` | `dict` | Unvalidated raw dict |
+
+### Convenience Functions
+
+| Function | Returns | Description |
+|----------|---------|-------------|
+| `get_chart_quotation(symbol, period="1D", accumulated=False, config=None)` | `ChartQuotation` | One-line fetch |
+| `get_latest_price(symbol, period="1D", accumulated=False, as_of=None, config=None)` | `Quotation \| None` | Latest traded quotation vs `as_of` |
+
+## Usage Examples
+
+### Example 1 — "What's the price right now?"
+
+```python
+from settfex.services.set import get_latest_price
+
+q = await get_latest_price("PTT")
+print("No trades yet" if q is None else f"{q.price} @ {q.local_datetime} (vol {q.volume})")
+```
+
+### Example 2 — Price as of a specific instant
+
+```python
+from datetime import datetime
+from settfex.services.set import get_latest_price
+
+# Naive datetime is interpreted as Asia/Bangkok local time
+q = await get_latest_price("CPALL", as_of=datetime(2026, 6, 19, 11, 0))
+print(q.price if q else "Nothing traded by 11:00")
+```
+
+### Example 3 — Build a simple intraday table
+
+```python
+from settfex.services.set import get_chart_quotation
+
+data = await get_chart_quotation("CPALL", period="1D")
+for q in data.quotations:
+    if q.volume is not None:                 # skip null/no-trade buckets
+        print(f"{q.local_datetime:%H:%M}  {q.price:>8}  {q.volume:>12,.0f}")
+```
+
+## Error Handling & Troubleshooting
+
+- **Empty symbol** → `ValueError`.
+- **Non-200 HTTP response** → `Exception` with the status code (e.g. `HTTP 403`).
+- **`get_latest_price` returns `None`** → nothing has traded by `as_of` (before the open, a holiday,
+  or an all-null series). Use the model's `get_latest_price()` for the `prior`-fallback scalar.
+- **Markets closed** → the `1D` series for the most recent session is returned; the latest traded
+  point is that session's last trade.