# Finhay Market

> Stock prices, commodities, macro indicators, charts, and company financials. Use for market analysis, price lookups, and corporate performance data.

- Skill: `finhay/finhay-market` (Agent Skill, multi-file: 34 files)
- Install (CLI): `npx skillmds@latest add finhay/finhay-market`
- Raw SKILL.md: https://api.skillmd.com/api/skills/finhay/finhay-market/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- License: MIT
- Author: finhay (https://skillmd.com/u/finhay)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/finhay/finhay-market

---


# Finhay Market

Read-only market data via the Finhay Securities Open API.

> **MANDATORY**: Ensure credentials are set (via environment variables `FINHAY_API_KEY`/`FINHAY_API_SECRET` or via `./finhay.sh auth`). Run `./finhay.sh doctor` to verify.

## Usage Examples

```bash
# Get real-time stock quote
./finhay.sh request GET /market/stock-realtime "symbol=VNM"

# Get gold spot price
./finhay.sh request GET /market/financial-data/gold

# Get historical OHLCV chart data
./finhay.sh request GET /market/price-histories-chart "symbol=VNM&resolution=1D&from=1609459200&to=1704067200"
```

## CLI Command Reference

| Command | Description |
|---------|-------------|
| `auth` | Configure API credentials interactively |
| `doctor` | Verify system dependencies and setup status |
| `request` | Execute signed API requests |
| `sync` | Update local skill definitions from source |

### Agent Attribution

> **REQUIRED**: Export `AGENT_NAME` before making any request. Use your tool's canonical lowercase identifier in `kebab-case` (e.g. `claude-code`). Any value is accepted as long as it consistently identifies your tool.

```bash
export AGENT_NAME=claude-code
./finhay.sh request GET /market/stock-realtime "symbol=VNM"
```

Sent as `X-FH-OPENAPI-AGENT` and embedded in `User-Agent`.

## Endpoints

| Endpoint | Description | Params |
|----------|-------------|--------|
| `/market/stock-realtime` | **Stock Quotes**: Real-time pricing for symbols or exchanges. | `symbol`, `symbols`, or `exchange` |
| `/market/index-realtime` | **Market Indices**: Real-time index values (VNINDEX, VN30, HNX30…). | `index` (comma-separated) |
| `/market/news` | **Market News**: Corporate events, dividends, and AGM dates. | `stock`, `from_date`, `to_date` |
| `/market/financial-data/gold` | **Gold Prices**: Real-time SJC and global gold spot prices. | — |
| `/market/financial-data/silver` | **Silver Prices**: Real-time silver spot prices. | — |
| `/market/financial-data/gold-chart` | **Gold Charts**: Historical gold price data for N days. | `days` |
| `/market/financial-data/silver-chart` | **Silver Charts**: Historical silver price data for N days. | `days` |
| `/market/financial-data/gold-providers` | **Gold by Provider**: Gold prices from PNJ, DOJI, SJC, etc. | — |
| `/market/financial-data/metal-providers` | **Metals by Provider**: Silver and other metal prices by provider. | — |
| `/market/financial-data/bank-interest-rates` | **Interest Rates**: Current bank deposit rates. | — |
| `/market/financial-data/cryptos/top-trending` | **Crypto Trends**: List of trending cryptocurrencies. | — |
| `/market/financial-data/macro` | **Macro Indicators**: CPI, PMI, and national interest rates. | `type`, `country` (`VN`,`US`; `JP`,`DE` only for `GOVERNMENT_10Y_BOND_YIELD`), `period` |
| `/market/financial-data/trading-economics` | **Trading Economics**: Historical economic indicators by country and category. | `country` (**required**: `China`, `Euro Area`, `Japan`, `United States`, `United Kingdom`, `Vietnam`), `category` (`GDP`, `Labour`, `Prices`, `Money`, `Trade`, `Government`, `Business`, `Consumer`, `Housing`), `year` |
| `/market/financial-data/global-news` | **Global News**: Paginated global financial news filtered by category. | `category` (`forex`, `commodities`, `economic-indicators`, `stock-market`, `cryptocurrency`), `page`, `page_size` (max 50) |
| `/market/financial-data/global-news/:id` | **Global News Detail**: Full article content by ID. | `:id` (path, **required**) |
| `/market/financial-data/economic-calendar-events` | **Economic Calendar**: Upcoming events for CN/EU/JP/US/UK/VN (CPI, Fed meetings). | `weeks` (default 1), `country` (e.g. `China`, `Vietnam`, `United States`) |
| `/market/financial-data/market` | **Global Indices**: Historical price for global indices, Mag7 stocks, commodities, forex — returns `[{date, value}]` desc. | `type` (SP500, NASDAQ, APPLE, GOLD, EURUSD…), `limit` (default 50, max 500) |
| `/fund-trading/public/fund-certificates` | **Fund List**: Available funds, sorted by 1y profit. | `fund-type`* (`STOCK_FUND`\|`BOND_FUND`\|`BALANCE_FUND`), `fund-company-id` |
| `/fund-trading/public/fund-companies` | **Fund Companies**: Management company list. | — |
| `/fund-trading/public/fund-certificates/benchmark/growth` | **Growth Simulation**: Projected return for a VND investment. | `fund-names`* (CSV), `amount`* (VND), `period`* |
| `/fund-trading/public/fund-certificates/benchmark/nav` | **NAV Comparison**: NAV time series for multiple funds. | `fund-names`*, `period` OR (`from-month`+`to-month` `yyyy-MM`) |
| `/fund-trading/public/fund-certificates/:fund/nav-histories` | **NAV History**: Price chart vs benchmarks. | `period` (default `ALL_TIME`) |
| `/fund-trading/public/fund-certificates/:fund/suggestions` | **Similar Funds**: Suggestions by criteria. | — |
| `/market/recommendation-reports/:symbol` | **Analyst Reports**: Professional stock recommendation reports. | `:symbol` (path) |
| `/market/price-histories-chart` | **Historical Data**: OHLCV data. | `symbol`, `resolution` (`1D`,`1H`,`4H`,`30`,`15`,`5`), `from`, `to` (seconds) |
| `/market/company-financial/overview` | **Corporate Ratios**: Key metrics (PE, PB, ROE, EPS). | `symbol` |
| `/market/company-financial/analysis` | **Financial Analysis**: Ratio trends. | `symbol`, `period` (`annual`,`quarterly`) |
| `/market/v2/financial-statement/statement` | **Financial Reports**: Income/Balance/Cash flow. | `symbol`, `type` (`income-statement`,`balance-sheet`,`cash-flow`), `period` (`annual`,`quarterly`) |

## Constraints

- **Read-only**: Execute `GET` requests only.
- **Privacy**: Mask sensitive credentials in all output.
- **Credentials**: If `FINHAY_API_KEY` or `FINHAY_API_SECRET` are missing, stop and ask the user to provide them or run `./finhay.sh auth`.
- **Parameters**: Pass exactly one identifier for stock quotes (symbol, symbols, or exchange).
- **Timeframes**: Price history timestamps must be in **seconds**. Default to the last 5 years if range is not provided.