API Overview

This page helps you quickly locate Stock SDK features and specific interfaces.

SDK Initialization

import { StockSDK } from 'stock-sdk';

const sdk = new StockSDK(options?);

Configuration Options

Option	Type	Default	Description
baseUrl	string	'https://qt.gtimg.cn'	Tencent API endpoint (can use proxy)
timeout	number	30000	Request timeout (ms)
retry	RetryOptions	See below	Retry configuration
headers	Record<string, string>	-	Custom request headers
userAgent	string	-	Custom User-Agent (may be ignored in browsers)
rateLimit	RateLimiterOptions	-	Rate limiting (prevent rate limit errors)
rotateUserAgent	boolean	false	Enable UA rotation (Node.js only)
circuitBreaker	CircuitBreakerOptions	-	Circuit breaker (pause on consecutive failures)
providerPolicies	Partial<Record<ProviderName, ProviderRequestPolicy>>	-	Override timeout, retry, rate limit, circuit breaker, and headers per provider

Retry Options (RetryOptions)

Option	Type	Default	Description
maxRetries	number	3	Maximum retry attempts
baseDelay	number	1000	Initial backoff delay (ms)
maxDelay	number	30000	Maximum backoff delay (ms)
backoffMultiplier	number	2	Backoff multiplier
retryableStatusCodes	number[]	[408, 429, 500, 502, 503, 504]	HTTP status codes to retry
retryOnNetworkError	boolean	true	Retry on network errors
retryOnTimeout	boolean	true	Retry on timeout
onRetry	function	-	Retry callback (attempt, error, delay) => void

Rate Limit Options (RateLimiterOptions)

Option	Type	Default	Description
requestsPerSecond	number	5	Maximum requests per second
maxBurst	number	= requestsPerSecond	Token bucket capacity (burst limit)

Recommendation

Configure requestsPerSecond: 3~5 to avoid triggering Eastmoney's rate limits.

Provider Overrides (ProviderRequestPolicy)

Global timeout / retry / rateLimit / circuitBreaker settings still work as the default policy.
providerPolicies only overrides those defaults for a specific provider, so existing initialization code remains compatible.

interface ProviderRequestPolicy {
  timeout?: number;
  retry?: RetryOptions;
  headers?: Record<string, string>;
  userAgent?: string;
  rateLimit?: RateLimiterOptions;
  rotateUserAgent?: boolean;
  circuitBreaker?: CircuitBreakerOptions;
}

Built-in provider names:

• tencent
• eastmoney
• sina
• linkdiary
• unknown

Circuit Breaker Options (CircuitBreakerOptions)

Disabled by Default

The circuit breaker is disabled by default and must be explicitly configured. Recommended for production environments to prevent cascade failures.

Option	Type	Default	Description
failureThreshold	number	5	Number of consecutive failures to trigger open state
resetTimeout	number	30000	Time in ms before transitioning to half-open
halfOpenRequests	number	1	Number of probe requests allowed in half-open state
onStateChange	function	-	State change callback (from, to) => void

Circuit Breaker States:

• CLOSED: Normal state, all requests allowed
• OPEN: Circuit is open, all requests rejected with CircuitBreakerError
• HALF_OPEN: Allows limited probe requests to test if service recovered

Full Configuration Example

const sdk = new StockSDK({
  timeout: 10000,
  headers: {
    'X-Request-Source': 'my-app',
  },
  userAgent: 'my-stock-app/1.0',
  
  // Retry configuration
  retry: {
    maxRetries: 5,
    baseDelay: 500,
    onRetry: (attempt, error, delay) => {
      console.log(`Retry ${attempt}, waiting ${delay}ms`);
    }
  },
  
  // Rate limiting (recommended)
  rateLimit: {
    requestsPerSecond: 5,
    maxBurst: 10,
  },
  
  // UA rotation (Node.js only)
  rotateUserAgent: true,
  
  // Circuit breaker (optional, recommended for production)
  circuitBreaker: {
    failureThreshold: 5,
    resetTimeout: 30000,
    onStateChange: (from, to) => {
      console.log(`Circuit breaker: ${from} -> ${to}`);
    }
  },

  // Override strategy for a specific provider
  providerPolicies: {
    eastmoney: {
      timeout: 12000,
      retry: {
        maxRetries: 5,
        baseDelay: 800,
      },
      rateLimit: {
        requestsPerSecond: 3,
        maxBurst: 3,
      },
      circuitBreaker: {
        failureThreshold: 3,
        resetTimeout: 30000,
      }
    }
  }
});

See Error Handling & Retry for details.

Real-time Quotes

• A-Share Quotes
• HK Stock Quotes
• US Stock Quotes
• Fund Quotes

K-Line Data

• History K-Line
• Minute K-Line
• Timeline

Technical Indicators

• Indicators Overview
• MA
• MACD
• BOLL
• KDJ
• RSI / WR
• BIAS
• CCI
• ATR
• OBV
• ROC
• DMI / ADX
• SAR
• KC

Industry Sectors

• Industry Sectors

Concept Sectors

• Concept Sectors

Batch & Extended

• Code Lists
• Search
• Batch Query
• Extended Data (Fund Flow, Trading Calendar, etc.)
• Dividend Details

Fund Flow (Deep)

• Individual / Market / Rank / Sector
• Northbound / Stock Connect

Limit-Up & Dragon-Tiger

• Limit-Up Pool / Stock Changes
• Dragon-Tiger List

Other Data

• Block Trade / Margin Trading