Agentic-Compaction-and-Pipleline-by-GLM-5/skills/finance/Finance_API_Doc.md

Finance API Complete Documentation

API Overview

Finance API provides comprehensive financial data access interfaces, including real-time market data, historical stock prices, and the latest financial news.

🌐 Access via API Gateway

This API is accessed through the web-dev-ai-gateway unified proxy service.

Gateway Configuration:

• Gateway Base URL: GATEWAY_URL (e.g., https://internal-api.z.ai)
• API Path Prefix: API_PREFIX (e.g., /external/finance)
• Authentication: Automatic (gateway injects x-rapidapi-host and x-rapidapi-key)
• Required Header: X-Z-AI-From: Z

URL Structure:

{GATEWAY_URL}{API_PREFIX}/{endpoint}

Example:

• Full URL: https://internal-api.z.ai/external/finance/v1/markets/search?search=Apple
• Breakdown:
  • https://internal-api.z.ai - Gateway base URL (GATEWAY_URL)
  • /external/finance - API path prefix (API_PREFIX)
  • /v1/markets/search - API endpoint path

Quick Start

# Get real-time quote for Apple
curl -X GET "{GATEWAY_URL}{API_PREFIX}/v1/markets/quote?ticker=AAPL&type=STOCKS" \
  -H "X-Z-AI-From: Z"

1. Market Data API

1.1 GET v2/markets/tickers - Get All Available Market Tickers

Parameters:

• page (optional, Number): Page number, default value is 1
• type (required, String): Asset type, optional values:
  • STOCKS - Stocks
  • ETF - Exchange Traded Funds
  • MUTUALFUNDS - Mutual Funds

curl example (via Gateway):

curl -X GET "{GATEWAY_URL}{API_PREFIX}/v2/markets/tickers?page=1&type=STOCKS" \
  -H "X-Z-AI-From: Z"

---

1.2 GET v1/markets/search - Search Stocks

Parameters:

• search (required, String): Search keyword (company name or stock symbol)

curl example (via Gateway):

curl -X GET "{GATEWAY_URL}{API_PREFIX}/v1/markets/search?search=Apple" \
  -H "X-Z-AI-From: Z"

Purpose: Used to find specific stock or company ticker codes

---

1.3 GET v1/markets/quote (real-time) - Real-time Quotes

Parameters:

• ticker (required, String): Stock symbol (only one can be entered)
• type (required, String): Asset type
  • STOCKS - Stocks
  • ETF - Exchange Traded Funds
  • MUTUALFUNDS - Mutual Funds

curl example (via Gateway):

curl -X GET "{GATEWAY_URL}{API_PREFIX}/v1/markets/quote?ticker=AAPL&type=STOCKS" \
  -H "X-Z-AI-From: Z"

---

1.4 GET v1/markets/stock/quotes (snapshots) - Snapshot Quotes

Parameters:

• ticker (required, String): Stock symbols, separated by commas

curl example:

curl --request GET \
  --url '{GATEWAY_URL}{API_PREFIX}/v1/markets/stock/quotes?ticker=AAPL%2CMSFT%2C%5ESPX%2C%5ENYA%2CGAZP.ME%2CSIBN.ME%2CGEECEE.NS'

Purpose: Batch get snapshot data for multiple stocks

---

2. Historical Data API

2.1 GET v1/markets/stock/history - Stock Historical Data

Parameters:

• symbol (required, String): Stock symbol
• interval (required, String): Time interval
  • 5m - 5 minutes
  • 15m - 15 minutes
  • 30m - 30 minutes
  • 1h - 1 hour
  • 1d - Daily
  • 1wk - Weekly
  • 1mo - Monthly
  • 3mo - 3 months
• diffandsplits (optional, String): Include dividend and split data
  • true - Include
  • false - Exclude (default)

curl example:

curl --request GET \
  --url '{GATEWAY_URL}{API_PREFIX}/v1/markets/stock/history?symbol=AAPL&interval=1d&diffandsplits=false'

Purpose: Get historical price data for specific stocks, used for technical analysis and backtesting

---

2.2 GET v2/markets/stock/history - Stock Historical Data V2

Parameters:

• symbol (required, String): Stock symbol
• interval (optional, String): Time interval
  • 1m, 2m, 3m, 4m, 5m, 15m, 30m
  • 1h, 1d, 1wk, 1mo, 1qty
• limit (optional, Number): Limit the number of candles (1-1000)
• dividend (optional, String): Include dividend data (true or false)

curl example:

curl --request GET \
  --url '{GATEWAY_URL}{API_PREFIX}/v2/markets/stock/history?symbol=AAPL&interval=1m&limit=640'

Purpose: Enhanced historical data interface

---

3. News API

3.1 GET v1/markets/news - Market News

Parameters:

• ticker (optional, String): Stock symbols, comma-separated for multiple stocks

curl example:

# Get general market news
curl --request GET \
  --url '{GATEWAY_URL}{API_PREFIX}/v1/markets/news'

# Get specific stock news
curl --request GET \
  --url '{GATEWAY_URL}{API_PREFIX}/v1/markets/news?ticker=AAPL,TSLA'

Purpose: Get the latest market news and updates

---

3.2 GET v2/markets/news - Market News V2

Parameters:

• ticker (optional, String): Stock symbol
• type (optional, String): News type (ALL, VIDEO, PRESS-RELEASE)

curl example:

curl --request GET \
  --url '{GATEWAY_URL}{API_PREFIX}/v2/markets/news?ticker=AAPL&type=ALL'

Purpose: Enhanced interface for getting latest market-related news

---

5. Stock Detailed Information API

5.1 GET v1/markets/stock/modules (asset-profile) - Company Profile

Parameters:

• ticker (required, String): Stock symbol

curl example:

curl --request GET \
  --url '{GATEWAY_URL}{API_PREFIX}/v1/markets/stock/modules?ticker=AAPL&module=asset-profile'

Purpose: Get company basic information, business description, management team, etc.

---

5.2 GET v1/stock/modules - Stock Module Data

Parameters:

• ticker (required, String): Stock symbol
• module (required, String): Module name (one per request)
  • Acceptable values: profile, income-statement, balance-sheet, cashflow-statement, statistics, calendar-events, sec-filings, recommendation-trend, upgrade-downgrade-history, institution-ownership, fund-ownership, major-directHolders, major-holders-breakdown, insider-transactions, insider-holders, net-share-purchase-activity, earnings, industry-trend, index-trend, sector-trend

curl example:

# Get specific module
curl --request GET \
  --url '{GATEWAY_URL}{API_PREFIX}/v1/markets/stock/modules?ticker=AAPL&module=statistics'

Purpose: Get one data module per request (price, financial, analyst ratings, etc.)

---

5.3 GET v1/markets/stock/modules (statistics) - Stock Statistics

Parameters:

• ticker (required, String): Stock symbol

curl example:

curl --request GET \
  --url '{GATEWAY_URL}{API_PREFIX}/v1/markets/stock/modules?ticker=AAPL&module=statistics'

Purpose: Get key statistical indicators such as PE ratios, market cap, trading volume

---

5.4 GET v1/markets/stock/modules (financial-data) - Get Financial Data

Parameters:

• ticker (required, String): Stock symbol
• module (required, String): financial-data

curl example:

curl --request GET \
  --url '{GATEWAY_URL}{API_PREFIX}/v1/markets/stock/modules?ticker=AAPL&module=financial-data'

Purpose: Get revenue, profit, cash flow and other financial indicators

---

5.5 GET v1/markets/stock/modules (sec-filings) - Get SEC Filings

Parameters:

• ticker (required, String): Stock symbol
• module (required, String): sec-filings

curl example:

curl --request GET \
  --url '{GATEWAY_URL}{API_PREFIX}/v1/markets/stock/modules?ticker=AAPL&module=sec-filings'

Purpose: Get files submitted by companies to the U.S. Securities and Exchange Commission

---

5.6 GET v1/markets/stock/modules (earnings) - Earnings Data

Parameters:

• ticker (required, String): Stock symbol

curl example:

curl --request GET \
  --url '{GATEWAY_URL}{API_PREFIX}/v1/markets/stock/modules?ticker=AAPL&module=earnings'

Purpose: Get quarterly and annual earnings information

---

5.7 GET v1/markets/stock/modules (calendar-events) - Get Calendar Events

Parameters:

• ticker (required, String): Stock symbol
• module (required, String): calendar-events

curl example:

curl --request GET \
  --url '{GATEWAY_URL}{API_PREFIX}/v1/markets/stock/modules?ticker=AAPL&module=calendar-events'

Purpose: Get upcoming earnings release dates, dividend dates, etc.

---

6. Financial Statements API

7.1 GET v1/markets/stock/modules (balance-sheet) - Balance Sheet

Parameters:

• ticker (required, String): Stock symbol

curl example:

curl --request GET \
  --url '{GATEWAY_URL}{API_PREFIX}/v1/markets/stock/modules?ticker=AAPL&module=balance-sheet'

Purpose: Get company balance sheet data

---

7.3 GET v1/markets/stock/modules (income-statement) - Income Statement

Parameters:

• ticker (required, String): Stock symbol

curl example:

curl --request GET \
  --url '{GATEWAY_URL}{API_PREFIX}/v1/markets/stock/modules?ticker=AAPL&module=income-statement'

Purpose: Get company income statement data

---

7.4 GET v1/markets/stock/modules (cashflow-statement) - Cash Flow Statement

Parameters:

• ticker (required, String): Stock symbol

curl example:

curl --request GET \
  --url '{GATEWAY_URL}{API_PREFIX}/v1/markets/stock/modules?ticker=AAPL&module=cashflow-statement'

Purpose: Get company cash flow statement data

---

Usage Flow Examples

Example 1: Find and Get Real-time Stock Data

# 1. Search company
GET /v1/markets/search?search=Apple

# 2. Get real-time quote
GET /v1/markets/quote?ticker=AAPL&type=STOCKS

# 3. Get detailed information
GET /v1/markets/stock/modules?ticker=AAPL&module=asset-profile

Example 2: Analyze Stock Investment Value

# 1. Get financial data
GET /v1/markets/stock/modules?ticker=AAPL&module=financial-data

# 2. Get earnings data
GET /v1/markets/stock/modules?ticker=AAPL&module=earnings

---

Usage Tips

1. Batch Query Optimization

# Get data for multiple stocks at once (snapshots endpoint) via Gateway
curl -X GET "{GATEWAY_URL}{API_PREFIX}/v1/markets/stock/quotes?ticker=AAPL,MSFT,GOOGL,AMZN,TSLA" \
  -H "X-Z-AI-From: Z"

2. Time Range Query

# Get historical data with specific interval via Gateway
curl -X GET "{GATEWAY_URL}{API_PREFIX}/v1/markets/stock/history?symbol=AAPL&interval=1d&diffandsplits=false" \
  -H "X-Z-AI-From: Z"

3. Combined Query Example

3. Combined Query Example

Python example (via Gateway):

import requests

# Gateway automatically handles authentication
headers = {
    'X-Z-AI-From': 'Z'
}

gateway_url = '{GATEWAY_URL}{API_PREFIX}/v1'
symbol = 'AAPL'

# Get real-time price
quote = requests.get(f'{gateway_url}/markets/quote?ticker={symbol}&type=STOCKS', headers=headers)

# Get company profile
profile = requests.get(f'{gateway_url}/markets/stock/modules?ticker={symbol}&module=asset-profile', headers=headers)

# Get financial data
financials = requests.get(f'{gateway_url}/markets/stock/modules?ticker={symbol}&module=financial-data', headers=headers)

---

Best Practices

Gateway Usage

1. Authentication Header - Always include X-Z-AI-From: Z header

API Usage

1. Rate Limiting: Pay attention to API call frequency limits to avoid being throttled
2. Error Handling: Implement comprehensive error handling mechanisms
3. Data Caching: Consider caching common requests to optimize performance
4. Batch Queries: Use comma-separated symbols parameter to query multiple stocks at once
5. Timestamps: Use Unix timestamps for historical data queries
6. Parameter Validation: Validate all required parameters before sending requests
7. Response Parsing: Implement robust JSON parsing and data validation

---