OpenStockAPI

English · Tiếng Việt · 日本語 · 简体中文 · 繁體中文

Free, open-source Python library to download historical stock data (OHLCV), real-time financial market quotes, orderbook, and news from Vietnam and global markets.

Read the Docs »  ·  Report Bug  ·  Request Feature

About The Project

OpenStockAPI is a free, open-source Python library designed to fetch, download, and standardize historical stock data (OHLCV), real-time financial market quotes, orderbook, ticks, news, and financials from Vietnam (HOSE, HNX, UPCOM), US, Japan, China, Hong Kong, and Australia stock markets, as well as global Crypto and Forex pairs.

It is designed to be the upstream data acquisition layer for financial applications, algorithmic trading systems, Excel add-ins, and Amibroker plugins — handling provider fallback, local caching, rate limiting, and tier-based access control — so your application logic never has to worry about data source reliability.

📘 A Vietnamese version of this README is available: README_VN.md

(back to top ↑)

Features

• ** Multi-market & Multi-asset Support** — Covers Vietnamese (VN) equities, Cryptocurrencies (Crypto), and Forex & Commodities.
• ** Automatic Multi-source Fallback** — Integrates providers (KBS, VCI, MSN, MAS, Maybank, Fmarket, Core Engine) with transparent automatic failover when any source is unavailable.
• ** JWT Handshake & Freemium Tier Access Control** — Supports short-lived JWT session token verification and Free, Pro, and Premium tier rate limits via a client-side Token Bucket Limiter.
• ** Async Support** — First-class async/await support via async_ohlcv() and async_crypto_ohlcv() for high-throughput data pipelines.

(back to top ↑)

Quick Start

import openstockapi as osapi

# Initialize with your API key (required for all tiers)
# Register for free at: https://openstockapi.com/register
osapi.init("free_YOUR_KEY")   # or "pro_YOUR_KEY" / "premium_YOUR_KEY"

# Historical OHLCV price data
df = osapi.ohlcv("VNM", resolution="1D", start="2025-01-01", end="2025-12-31")
print(df.head())

# Fetch Cryptocurrency data
btc_ohlcv = osapi.crypto_ohlcv("BTCUSDT", interval="1h", limit=5)
print(btc_ohlcv)

# Fetch Forex & Commodities data
rates = osapi.forex_rates(base="USD")
gold_price = osapi.commodities_prices(symbol="GOLD", range_val="5d", interval="1h")
print(f"USD/VND: {rates['rates']['VND']} | Gold: {gold_price['regularMarketPrice']} USD")

(back to top ↑)

Installation

Minimum install:

pip install openstockapi

With Pandas DataFrame & Excel export support:

pip install openstockapi[pandas]

Requirements: Python 3.8+

(back to top ↑)

Usage & Documentation

Full documentation, use case examples, and sample outputs are available in the User Guide:

User Guide — Getting Started

(back to top ↑)

Supported Providers

Providers are grouped by market/asset class. Within each group, they are tried in priority order — if one fails, the next is used automatically.

Vietnamese Stock Market

Cryptocurrency

Crypto data is sourced through the OpenStockAPI Core Engine — a managed, closed-source aggregation layer with automatic multi-provider failover and normalization. The specific upstream exchanges and data sources are not disclosed.

Forex & Commodities

Forex and Commodities data is sourced through the OpenStockAPI Core Engine with automatic fallback across multiple rate and price providers. Specific upstream sources are not disclosed.

| Forex Spot Rates | Free | | Forex OHLCV | Free | | Commodities Prices (Gold, Oil, etc.) | Free | | Global Indices & ETF (SPY, QQQ) | Free | | Cross-broker Rate Comparison | Pro | | Supported Forex Symbols List | Free | | Forex & Financial News | Free | | Global Macro Events Calendar | Free |

Australian Stock Market

US Stock Market

Japanese Stock Market

China Stock Market

HK Stock Market

(back to top ↑)

Data Modules Overview

openstockapi
├── ohlcv()                  # Historical Stock OHLCV (sync)
├── async_ohlcv()            # Historical Stock OHLCV (async)
├── profile()                # Stock Company profile
├── derivative_profile()     # Stock Derivatives (Futures/Warrants) profile
├── balance_sheet()          # Stock Balance sheet
├── income_statement()       # Stock Income statement
├── cashflow()               # Stock Cash flow statement
├── ratios()                 # Stock Financial ratios
├── quote()                  # Stock Realtime price quote
├── order_book()             # Stock Order book depth
├── market_index()           # Stock Market index OHLCV
├── macro_indicators()       # Macroeconomic data
├── fund_details()           # Stock Mutual fund info
├── company_news()           # Stock Corporate news (supports routing to Crypto/Forex via market param)
├── company_events()         # Stock Corporate events (supports routing to Crypto/Forex via market param)
├── vn_heatmap()             # VN Stock Market Heatmap data & logos
│
├── crypto_ohlcv()           # Historical Crypto OHLCV (sync)
├── async_crypto_ohlcv()     # Historical Crypto OHLCV (async)
├── crypto_depth()           # Crypto Order book depth
├── crypto_derivatives()     # Crypto Derivatives indicators
├── crypto_footprint()       # Crypto Delta footprint heatmap
├── simulate_leverage()      # Crypto Margin/leverage position simulator
├── crypto_symbols()         # Supported Crypto symbols list
├── crypto_tickers()         # Realtime Crypto tickers list
├── crypto_options_instruments() # Supported Crypto Options list
├── crypto_options_chain()   # Crypto Options chain data
├── crypto_options_ticker()  # Crypto Options detailed Greeks
├── crypto_news()            # Crypto News articles
├── crypto_events()          # Crypto Calendar events
├── crypto_profile()         # Crypto Token profile & logo
├── crypto_heatmap()         # Cryptocurrency market Heatmap
├── CryptoStream             # Realtime WebSocket streaming client
│
├── forex_rates()            # Forex Exchange rates
├── forex_ohlcv()            # Historical Forex OHLCV
├── commodities_prices()     # Commodities Prices (Gold, Oil)
├── global_indices_etf()     # Global indices and ETFs (SPY, QQQ)
├── compare_rates()          # Forex cross-broker arbitrage rates comparison
├── forex_symbols()          # Supported Forex symbols list
├── forex_news()             # Forex & Financial News articles
├── forex_events()           # Global Macro Events Calendar
├── forex_profile()          # Forex Currency Pair profile & cdn flags
│
├── asx_symbols()            # Supported ASX symbols list
├── asx_ohlcv()              # Historical ASX OHLCV
├── asx_profile()            # ASX Company profile
├── asx_balance_sheet()      # ASX Balance sheet
├── asx_income_statement()   # ASX Income statement
├── asx_cashflow()           # ASX Cash flow statement
├── asx_ratios()             # ASX Financial ratios
├── asx_dividends()          # ASX Dividend history
├── asx_announcements()      # ASX PDF announcements feed
├── asx_news()               # ASX Company news
├── asx_heatmap()            # ASX Market Heatmap data & logos
│
├── us_ohlcv()               # Historical US Stock OHLCV
├── us_profile()             # US Stock Company profile
├── us_financials()          # US Stock Financial statements
├── us_balance_sheet()       # US Stock Balance sheet
├── us_income_statement()    # US Stock Income statement
├── us_cashflow()            # US Stock Cash flow statement
├── us_ratios()              # US Stock Financial ratios
├── us_dividends()           # US Stock Dividend history
├── us_splits()              # US Stock Stock split history
├── us_calendar()            # US Stock Corporate calendar
├── us_news()                # US Stock Company news
├── us_heatmap()             # US Stock Market Heatmap data & logos
│
├── jp_symbols()             # JP Stock symbols list
├── jp_ohlcv()               # Historical JP Stock OHLCV
├── jp_profile()             # JP Stock Company profile
├── jp_financials()          # JP Stock Financial statements
├── jp_balance_sheet()       # JP Stock Balance sheet
├── jp_income_statement()    # JP Stock Income statement
├── jp_cashflow()            # JP Stock Cash flow statement
├── jp_ratios()              # JP Stock Financial ratios
├── jp_dividends()           # JP Stock Dividend history
├── jp_splits()              # JP Stock Stock split history
├── jp_calendar()            # JP Stock Corporate calendar
├── jp_news()                # JP Stock Company news
├── jp_heatmap()             # JP Stock Market Heatmap data & logos
│
├── cn_symbols()             # CN Stock symbols list
├── cn_ohlcv()               # Historical CN Stock OHLCV
├── cn_profile()             # CN Stock Company profile
├── cn_financials()          # CN Stock Financial statements
├── cn_balance_sheet()       # CN Stock Balance sheet
├── cn_income_statement()    # CN Stock Income statement
├── cn_cashflow()            # CN Stock Cash flow statement
├── cn_ratios()              # CN Stock Financial ratios
├── cn_dividends()           # CN Stock Dividend history
├── cn_splits()              # CN Stock Stock split history
├── cn_quote()               # CN Stock Realtime price quote (Pro)
├── cn_order_book()          # CN Stock Order book depth (Pro)
├── cn_tick()                # CN Stock Intraday ticks (Pro)
├── cn_heatmap()             # CN Stock Market Heatmap data & logos
│
├── hk_symbols()             # HK Stock symbols list
├── hk_ohlcv()               # Historical HK Stock OHLCV
├── hk_profile()             # HK Stock Company profile
├── hk_financials()          # HK Stock Financial statements
├── hk_balance_sheet()       # HK Stock Balance sheet
├── hk_income_statement()    # HK Stock Income statement
├── hk_cashflow()            # HK Stock Cash flow statement
├── hk_ratios()              # HK Stock Financial ratios
├── hk_dividends()           # HK Stock Dividend history
├── hk_splits()              # HK Stock Stock split history
├── hk_calendar()            # HK Stock Corporate calendar
├── hk_heatmap()             # HK Stock Market Heatmap data & logos
└── hk_news()                # HK Stock Company news

(back to top ↑)

Roadmap

• Vietnamese equity OHLCV (KBS, VCI, MSN)
• Financial statements (MAS, VCI)
• Macroeconomic indicators (World Bank, Maybank)
• Mutual fund data (Fmarket)
• Corporate news & events (KBS, VCI)
• Cryptocurrency data (Core Engine)
• Crypto Options data (Deribit, OKX)
• Forex & Commodities data (Core Engine)
• Australian equity market data (ASX)
• US equity market data (US)
• WebSocket streaming quotes

(back to top ↑)

Contributing

Contributions are welcome! If you'd like to add a new data provider, please use our Connector Development Kit (CDK) which automates boilerplate code generation and validation.

For a step-by-step guide on how to add a provider using CDK, please refer to the CDK Contributor Guide.

General workflow:

1. Fork the repository
2. Create a feature branch: git checkout -b feature/new-provider
3. Generate provider template: openstock-cdk generate --name <name> --market <market> --type <type>
4. Implement your API parser logic and write tests
5. Run tests: pytest tests/cdk/ -v
6. Open a Pull Request

(back to top ↑)

Changelog

See all version updates, new features, and bug fixes at:

CHANGELOG.md

(back to top ↑)

License

Distributed under the GNU Affero General Public License v3.0 (AGPL-3.0). See LICENSE for more information.

(back to top ↑)