clawshire-annual-report

ClawShire Annual Report Data Query Skill

Structured extraction result query service for annual reports of Beijing Stock Exchange listed companies. Covers Beijing Stock Exchange listed companies whose securities codes start with 4/8/9, returning standardized fields such as revenue, profit, dividends, and strategic highlights for direct reasoning by the Agent.

Service address: https://api.clawshire.cn

---

Pre-check

Before executing any API call, you must check whether the CLAWSHIRE_API_KEY environment variable exists.

• Only determine whether it exists;must notdisplay the key content in plaintext in the output
• If it does not exist, guide the user to register and obtain one:https://clawshire.cn

---

Authentication Method

All request headers carry:

Authorization: Bearer $CLAWSHIRE_API_KEY

---

Beijing Stock Exchange Notes

Characteristics of securities codes of Beijing Stock Exchange listed companies:

• 4 prefix: Beijing Stock Exchange stocks (e.g., 430000 range)
• 8 prefix: Beijing Stock Exchange stocks (e.g., 830000 range)
• 9 prefix: Beijing Stock Exchange stocks (e.g., 920000 range)

When querying annual reports, infotype is fixed to 年报, no need for the user to specify.

---

Workflow

Workflow 1: Query annual reports by securities code

Applicable scenario: The user wants to query the annual report extraction results of a certain Beijing Stock Exchange company.

Steps:

1. Confirm the Beijing Stock Exchange securities code (a 6-digit code starting with 4/8/9)
2. Optional: specify the year range (start_date、end_date）
3. Call GET /api/v1/stock/{sec_code}/announcements, fixed infotype=年报
4. Display the results: extracted fields such as company name, annual report period, revenue, profit, dividends, strategic highlights, etc.

Example:

查询九典制药（833359）2024 年报
→ GET /api/v1/stock/833359/announcements?infotype=年报&start_date=2024-01-01&end_date=2025-12-31

---

Workflow 2: Query annual reports of the entire Beijing Stock Exchange market by year

Applicable scenario: The user wants to query the annual report extraction results of all companies on the Beijing Stock Exchange for a certain year.

Steps:

1. Confirm the year (e.g., 2024)
2. Convert the year to a date range:start_date={year}-01-01，end_date={year+1}-12-31
3. Call GET /api/v1/announcements, fixed infotype=年报
4. Display the result list, including core extracted fields such as company name, securities code, revenue, profit, etc.

Note: Beijing Stock Exchange annual reports are usually disclosed between March and April of the following year. For example, to query 2024 annual reports, end_date should be set to 2025-06-30.

---

Workflow 3: Query annual reports by announcement link

Applicable scenario: The user has the original link to a Beijing Stock Exchange annual report and wants to obtain the structured extraction results.

Steps:

1. Obtain the original annual report link provided by the user
2. Call GET /api/v1/met_link?met_link=<url_encoded_link>&infotype=年报
3. Display the complete structured extraction content

---

Workflow 4: Obtain API Key

Steps:

1. Guide the user to log in to the console:https://clawshire.cn
2. Create an API Key in the console
3. Set the environment variable:

   export CLAWSHIRE_API_KEY="sk-xxxxxxxx"
   

---

Workflow 5: Financial Risk Analysis (authentication required)

Applicable scenario: The user needs to conduct an in-depth risk assessment of a listed company's annual report. Calls 25+ analysis rules, outputting an overall risk rating (low/medium/high) and detailed analysis of each rule.

Prerequisites:

• A valid CLAWSHIRE_API_KEY
• The financial analysis API requires permissions to be enabled in the console (coming soon)

Steps:

1. Get the target company's annual report PDF file path (or download the PDF corresponding to the annual report URL)
2. Call POST /api/v1/financial-analysis/jobs to upload the PDF
3. Use the returned job_id to poll GET /api/v1/financial-analysis/jobs/{job_id}
4. After the analysis is complete, display the risk rating and the list of high/medium risk rules

Note:

• The financial analysis API is hosted at https://api.clawshire.cn, and shares authentication with the announcement data API
• Analysis usually takes 2-8 minutes, and the PDF can be up to 100MB
• View all available rules:GET /api/v1/financial-analysis/rules

Example:

上传年报 PDF 进行风险分析
→ POST /api/v1/financial-analysis/jobs (file=年报.pdf)
← {"id": "job_xxxxx", "status": "pending", ...}

轮询获取结果
→ GET /api/v1/financial-analysis/jobs/job_xxxxx
← {"status": "completed", "overall_risk_level": "medium", "rule_results": [...]}

Using the script:

# 分析 PDF 文件（需要 CLAWSHIRE_API_KEY）
python scripts/financial_analysis_client.py analyze path/to/年报.pdf

# 或指定语言（默认中文）
python scripts/financial_analysis_client.py analyze path/to/年报.pdf --lang en

# 查看所有分析规则
python scripts/financial_analysis_client.py rules

---

Result display specification

Standard annual report output format

Each annual report result is displayed in the following structure (based on the actual fields returned by the API):

1. Basic information

• Company：{sec_name}（{sec_code}）
• Reporting period：{year}年年度报告
• Announcement date：{doc_date}
• Original link：{met_link}

2. Audit information

Extract the extracted_info category from 深交所-定期报告审计意见 :

• Audit firm:domestic_audit_firm
• Signing certified public accountant:domestic_signing_cpa
• Audit opinion:domestic_audit_opinion_type

3. Key financial indicators

Extract the extracted_info category from 北交所-主要财务指标表 , and display it as a comparison table:

Indicator	Current period amount	Prior period amount	Year-over-year change
Operating revenue	Original_current period amount	Original_prior period amount	Calculate percentage
Net profit	Original_current period amount	Original_prior period amount	Calculate percentage
Net profit excluding non-recurring items	Original_current period amount	Original_prior period amount	Calculate percentage
Operating cash flow	Original_current period amount	Original_prior period amount	Calculate percentage
Basic earnings per share	Original_current period amount	Original_prior period amount	Calculate percentage
Return on equity (weighted)	Original_current period amount	Original_prior period amount	Calculate difference

Important: All amounts must retain the original decimal places returned by the API, and must not be rounded or simplified.

4. Income statement summary

Extract the extracted_info category from 北交所-通用类利润表_合并 :

Item	Current period amount	Prior period amount
Operating revenue	Original_current period amount	Original_prior period amount
Operating cost	Original_current period amount	Original_prior period amount
Selling expenses	Original_current period amount	Original_prior period amount
Administrative expenses	Original_current period amount	Original_prior period amount
Research and development expenses	Original_current period amount	Original_prior period amount
Financial expenses	Original text_Current period amount	Original text_Prior period amount
Operating profit	Original text_Current period amount	Original text_Prior period amount
Total profit	Original text_Current period amount	Original text_Prior period amount

5. Share capital structure

From extracted_info extract 深交所-公司股本结构 category:

Item	Quantity
Total share capital	Original text_Total share capital shares
Tradable shares	Original text_Tradable shares shares
Restricted tradable shares	Original text_Restricted tradable shares shares
Shareholding of controlling shareholder and actual controller	Original text_Controlling shareholder, actual controller shares

Number of shareholders: from 深交所-公司股东人数 extract total_shareholders

6. Top ten shareholders

From extracted_info extract 北交所-公司十大股东表 category:

Rank	Shareholder	Shareholding ratio	Number of shares held
Original text_Shareholder rank	Original text_Shareholder name	Original text_Shareholding ratio (%)	Original text_Number of shares held (shares)

Note: The shareholding ratio retains the original precision returned by the API (usually 4 decimal places)

7. Dividend situation

From extracted_info extract 深交所-分红转赠 category:

• Dividend per share:dividend_ratio_rmb yuan
• Capital reserve conversion per share:transfer_share_ratio
• Bonus shares per share:bonus_share_ratio

If there is no dividend data, look for the "Announcement on Explanation of No Profit Distribution for the Year" published on the same day

extracted_info All fields in should be displayed completely without trimming.

---

Table output specifications

When the user requests "export CSV", "generate Excel", or "output table":

1. Call the API to obtain data (same as the above workflow)
2. Flatten the extracted_info fieldof each annual reportinto one row:
   • Fixed columns:证券代码、公司名称、公告标题、公告日期、原文链接
   • Dynamic columns:extracted_info all keys in (take the union across entries, fill in blanks for missing)
3. Use clawshire_annual_client.py --output csv or --output excel parameters to directly generate the file
4. Inform the user of the file save path

Example instruction:

# 输出 CSV
python clawshire_annual_client.py list --year 2024 --output csv

# 输出 Excel（需要 openpyxl）
python clawshire_annual_client.py list --year 2024 --output excel

# 单公司年报导出
python clawshire_annual_client.py stock 833359 --output excel

Field flattening rules:

• extracted_info When it is a list, take the first item (main extraction result)
• Expand nested dictionaries into 父key_子key format
• Keep numeric values as the original strings, do not perform unit conversion

---

Call limits

• Free account: each API Key has a total of 100 call credits
• Annual report data is billed per item (each annual report = 1 call)
• For a single query, it is recommended that page_size not exceed 20
• Annual reports are usually 1 per company per year, and the total volume is limited, so all can be retrieved without pagination

---

Error handling

Error code	Meaning	Handling method
400	Parameter error	Check the date format (YYYY-MM-DD) and the securities code format
401	Invalid API Key	Prompt the user to check the CLAWSHIRE_API_KEY environment variable
402	Insufficient quota	Prompt the user to log in to the console to top up or apply for a quota increase
404	Resource does not exist	Confirm whether the securities code is for the Beijing Stock Exchange (starting with 4/8/9), or whether the company's annual report has not yet been extracted
500	Server error	Retry later, or visit https://clawshire.cn to check the service status