Read-only market data via the Finhay Securities Open API.
MANDATORY: Ensure credentials are set (via environment variables
FINHAY_API_KEY/FINHAY_API_SECRETor via./finhay.sh auth). Run./finhay.sh doctorto verify.
Usage Examples
# 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_NAMEbefore making any request. Use your tool's canonical lowercase identifier inkebab-case(e.g.claude-code). Any value is accepted as long as it consistently identifies your tool.
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
GETrequests only. - Privacy: Mask sensitive credentials in all output.
- Credentials: If
FINHAY_API_KEYorFINHAY_API_SECRETare 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.