finhay-market

The saved excerpt is a snapshot from review. The external source remains the complete and most current version.

---
name: finhay-market
description: "Stock prices, commodities, macro indicators, charts, and company financials. Use for market analysis, price lookups, and corporate performance data."
license: MIT
metadata:
  author: Finhay Securities
  version: "2.0.0"
---

# 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-da