DOCSEARCHbyAlgolia
Submit Docs

stock-sdk

repository·master·Indexed 23 days ago

https://github.com/chengzuopeng/stock-sdk

A zero-dependency JavaScript/TypeScript SDK for accessing real-time and historical stock market data for A-shares, HK, US, and Funds. Compatible with browser and Node.js, it features a namespaced API (v2), a built-in CLI, and an MCP server for AI integration. The SDK includes specialized modules for technical indicators, signal calculation, local screening, and backtesting, with subpath exports to support tree-shaking.

Tokens
130.4K
Snippets
327
Records
596
Agent score
78%

What's inside stock-sdk

  1. Overview of Stock SDK features

    master

    Stock SDK is a lightweight, zero-dependency library for browser and Node.js 18+ environments. Key features include:

    • Namespaced API: Methods are organized by domain (e.g., sdk.quotes.cn(), sdk.kline.cn(), sdk.options.etf.dailyKline()).
    • Dual-runtime Support: Works in both the browser and Node.js using ESM and CJS with subpath imports.
    • Unified Data Contract: Uses a consistent Quote model with base fields like symbol, market, timestamp, and tz.
    • Indicators & Signals: Includes 14 built-in indicators and a signal layer (e.g., golden/death cross, overbought/oversold) available via subpath imports from stock-sdk/indicators and stock-sdk/signals.
    • Screener & Backtest: Provides a declarative screener for market-wide data and a local backtest engine.
    • CLI & MCP: Includes a CLI for terminal-based quote fetching and a built-in MCP (Model Context Protocol) server for AI tools, designed to not increase the main package size.

  2. Introduction to stock-sdk

    master

    Overview

    stock-sdk is a zero-runtime-dependency stock market SDK designed to run in both the browser and Node.js 18+. It provides a unified data contract for A-shares, Hong Kong stocks, US stocks, funds, futures, and options.

    Key Features

    • Zero Dependencies: All logic (symbol parsing, indicators, signals, screener, caching, and MCP protocol) is hand-written and pure.
    • Dual-Runtime: Supports both ESM and CJS for use in browsers and Node.js.
    • Tree-shakable: Use subpath exports (e.g., stock-sdk/indicators, stock-sdk/signals, stock-sdk/symbols) to import only the logic you need and avoid pulling in the request layer.
    • Fully Typed: All public APIs include TypeScript types and JSDoc.

    Capabilities

    • Quotes & K-lines: Real-time quotes, historical K-lines, and technical indicators.
    • Market Data: Capital flow, dragon-tiger lists, block trades, and margin data.
    • Analysis Tools: A declarative screener and a local backtest engine.
    • Interfaces: A Command Line Interface (CLI) and a Model Context Protocol (MCP) server for AI tools.

  3. Overview of stock-sdk v2

    master

    What is stock-sdk?

    stock-sdk is a zero-runtime-dependency stock market data SDK designed for both Browsers and Node.js 18+. It provides data for A-shares, Hong Kong stocks, US stocks, funds, futures, and options, including K-lines, fund flows, and dragon-tiger lists. It also includes built-in technical indicators, signals, a stock screener, backtesting engine, CLI, and MCP services.

    Key Characteristics

    • Zero Dependencies: All logic (symbol parsing, indicators, signals, screener, cache, MCP) is hand-written pure logic with no runtime dependencies in package.json.
    • Dual-Runtime: Runs in both Browser and Node.js 18+ environments, shipping both ESM and CJS.
    • Tree-shakable / On-demand Imports: Beyond the main entry point, it provides subpath exports (e.g., stock-sdk/indicators, stock-sdk/signals, stock-sdk/symbols) so you only import the logic you need without pulling in the request layer or all providers.
    • Full Type Safety: All public APIs are fully typed with TypeScript and JSDoc.

  4. Overview of Stock SDK

    master
    The stock-sdk is a lightweight, zero-dependency stock market data SDK designed for both Browser and Node.js environments. It provides comprehensive support for multiple markets, K-line data, technical indicators, futures, options, and AI/MCP integration. It is built with full TypeScript support for a high-quality developer experience.

  5. Access Dragon-Tiger List (龙虎榜) data via sdk.dragonTiger

    master

    The sdk.dragonTiger namespace provides A-share Dragon-Tiger List data, including daily listing details, individual stock statistics, institutional buying/selling, branch rankings, and specific seat details for a given stock on a specific date.

    All monetary fields are in CNY (RMB). Date-related fields follow a unified contract including date, timestamp (number | null), and tz.

    To use these features, initialize the StockSDK and access the dragonTiger property.

    import { StockSDK } from 'stock-sdk'

const sdk = new StockSDK()
// Access dragonTiger methods here

  6. Access A-share margin trading data with sdk.margin

    master

    The sdk.margin namespace provides A-share margin trading (融资融券) data, covering both market-level macro statistics and individual stock-level details.

    Data Units:

    • Monetary fields (e.g., finBalance) are in CNY.
    • Quantity fields (e.g., loanBalance in targetList) are in shares.
    • Date-related items follow a unified data contract including date, timestamp (number | null), and tz.
    import { StockSDK } from 'stock-sdk'

const sdk = new StockSDK()
const account = await sdk.margin.accountInfo()

  7. Access A-share block trade data with sdk.blockTrade

    master

    The sdk.blockTrade namespace provides access to A-share block trade (大宗交易) data, including macro market overviews, individual transaction details, and daily statistics aggregated by stock.

    All monetary fields are in CNY (RMB). Date-related fields follow a unified data contract including date, timestamp (number | null), and tz.

    import { StockSDK } from 'stock-sdk'

const sdk = new StockSDK()
const stat = await sdk.blockTrade.marketStat()

  8. Overview of MCP Tools in stock-sdk

    master

    The stock-sdk MCP (Model Context Protocol) server exposes the SDK's read-only namespace methods as tools that an AI model can call. Each tool is defined by a ToolDef containing a name, description, a JSON Schema inputSchema, and an invoke function that maps arguments to the underlying SDK call.

    Important Constraints:

    • Read-Only Only: Only read-only namespace methods are exposed. Write operations and debug-only *Raw methods are not available as tools.
    • Single Source of Truth: The tool manifest is shared between the MCP server and the CLI, ensuring consistent tool definitions across both interfaces.
    • Implementation-Driven: The exact tool names and input fields follow the final manifest implementation.

  9. Overview of sdk.options namespace

    master

    The sdk.options namespace provides access to various option markets, including CFFEX index options, SSE ETF options, commodity options, and the Dragon-Tiger list. It is organized into the following sub-namespaces:

    • sdk.options.index: CFFEX stock-index options.
    • sdk.options.etf: SSE ETF options.
    • sdk.options.commodity: Commodity options.
    • sdk.options.cffex: Full CFFEX option quote list.
    • sdk.options.lhb: Option Dragon-Tiger list (accessed via top-level method).
    import { StockSDK } from 'stock-sdk';

const sdk = new StockSDK();

const spot = await sdk.options.index.spot('io', 'io2504');
const kline = await sdk.options.etf.dailyKline('10009633');
const lhb = await sdk.options.lhb('510050', '2022-01-21');

  10. Understand the `sdk.options` namespace structure

    master

    The sdk.options namespace provides comprehensive coverage for options market data, including CFFEX index options, SSE ETF options, commodity options, and the Options Dragon-Tiger List (LHB). It is organized into a two-level namespace hierarchy:

    • sdk.options.index: CFFEX Index Options (中金所股指期权)
    • sdk.options.etf: SSE ETF Options (上交所 ETF 期权)
    • sdk.options.commodity: Commodity Options (商品期权)
    • sdk.options.cffex: Full CFFEX Options real-time quotes (中金所全量期权)
    • sdk.options.lhb: Options Dragon-Tiger List (期权龙虎榜) - accessed as a top-level method under options.
    import { StockSDK } from 'stock-sdk';

const sdk = new StockSDK();

// Examples of accessing different namespaces
const spot = await sdk.options.index.spot('io', 'io2504');
const kline = await sdk.options.etf.dailyKline('10009633');
const lhb = await sdk.options.lhb('510050', '2022-01-21');

  11. Use the Namespaced API in v2

    master

    In v2, the API has moved from a flat structure to a namespaced structure organized by domain. This replaces the long, flat method names used in v1.

    Available Namespaces

    • quotes: Real-time quotes
    • codes: Per-market code lists
    • batch: Full-market or batch quotes
    • kline: Historical K-lines
    • board: Industry/concept boards
    • options: Derivatives (Index/ETF/Commodity)
    • futures: Domestic & global futures
    • fundFlow: Capital flow data
    • northbound: Northbound capital
    • marketEvent: Limit-up/changes
    • dragonTiger: Dragon-tiger lists
    • blockTrade: Block trades
    • margin: Margin data
    • fund: Fund extensions
    • calendar: Trading calendars
    • reference: Reference data
    • sdk.search(keyword): Top-level search functionality

    Note: v2 is a hard cutover. There is no backward compatibility for v1 methods.

    import { StockSDK } from 'stock-sdk'

const sdk = new StockSDK()

// v2 namespaced calls
await sdk.quotes.cn(['sh600519'])              // A-share full quotes
await sdk.kline.cn('600519', { period: 'daily' }) // A-share historical K-line
await sdk.options.etf.dailyKline('10004336')    // ETF option daily K-line

  12. Understand the v2 Namespaced API structure

    master

    In version 2 (v2) of stock-sdk, the API has moved from a flat structure to a namespaced structure. Instead of calling methods directly on the sdk object, you access them through specific namespaces related to the data type (e.g., sdk.quotes.cn()).

    Key Namespaces:

    • sdk.quotes: Real-time quotes for various markets (.cn, .hk, .us, .fund, etc.).
    • sdk.codes: Stock code lookups.
    • sdk.batch: Batch processing for multiple codes.
    • sdk.kline: K-line (candlestick) data, including minute intervals and technical indicators.
    • sdk.chips: Chip distribution data (profit ratio, avg cost, etc.).
    • sdk.board: Industry and concept boards.
    • sdk.fundFlow: Market and sector fund flow data.
    • sdk.marketEvent: Market events like limit-up pools (.ztPool) or stock changes.
    • sdk.calendar: Trading day and market status information.
    • sdk.search(keyword): Top-level search functionality.