clawshire-financial-analysis

ClawShire Financial Risk Analysis Skill

Perform in-depth financial risk assessment on a listed company's annual report PDF. After uploading the PDF, the system automatically parses, extracts, and analyzes it, outputting an overall risk rating (low/medium/high) and detailed conclusions for each rule.

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 plain text in the output
• If it does not exist, guide the user to log in to the console to create it:https://clawshire.cn

---

Authentication method

All request headers carry:

Authorization: Bearer $CLAWSHIRE_API_KEY

---

Workflow

Workflow 1: Analyze annual report PDF

Applicable scenario: The user has an annual report PDF file and needs to quickly obtain a financial risk assessment conclusion.

Steps:

1. Confirm the PDF file path (local file, maximum 100MB)
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}, until status is completed
4. Display the analysis results: overall risk rating + list of high/medium risk rules

Note:

• Analysis usually takes 2-8 minutes, please wait patiently
• Recommended polling interval is 5 seconds

Example:

上传 PDF
→ POST /api/v1/financial-analysis/jobs
  Content-Type: multipart/form-data
  file=年报.pdf, language=zh

← {"id": "job_xxxxx", "status": "pending", ...}

轮询结果
→ GET /api/v1/financial-analysis/jobs/job_xxxxx
← {
    "status": "completed",
    "overall_risk_level": "medium",
    "rule_results": [
      {"display_name_zh": "收入真实性", "risk_level": "high", ...},
      ...
    ]
  }

Using the script:

# 终端输出风险摘要
python skills/clawshire-financial-analysis/scripts/financial_analysis_client.py analyze path/to/年报.pdf

# 导出 HTML 报告（自动命名，保存到同目录）
python skills/clawshire-financial-analysis/scripts/financial_analysis_client.py analyze path/to/年报.pdf --output html

# 英文报告
python skills/clawshire-financial-analysis/scripts/financial_analysis_client.py analyze path/to/report.pdf --lang en --output html

---

Workflow 2: View all analysis rules

Applicable scenario: The user wants to know which risk analysis dimensions the system supports.

Steps:

1. Call GET /api/v1/financial-analysis/rules
2. Display the rule list: rule name, category, description

Using the script:

python skills/clawshire-financial-analysis/scripts/financial_analysis_client.py rules

---

Workflow 3: 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 and enable financial analysis permissions
3. Set the environment variable:

export CLAWSHIRE_API_KEY="sk-xxxxxxxx"

---

Result display specification

After analysis is complete, you must display:

• Overall risk rating: Low risk / Medium risk / High risk
• High risk items: List all risk_level = "high" rule names and conclusions
• Medium risk items: List all risk_level = "medium" rule names and conclusions
• Rule statistics: A total of N rules analyzed, with how many high/medium/low/not applicable each
• Analysis duration: The time from submission to completion

If there are no high/medium risk items, clearly state "No high-risk or medium-risk items found."

---

API description

Upload analysis task

POST /api/v1/financial-analysis/jobs
Authorization: Bearer {api_key}
Content-Type: multipart/form-data

file: <PDF 文件>
language: zh | en  （默认 zh）

Response:

{
  "id": "job_xxxxx",
  "status": "pending",
  "created_at": "2026-03-20T10:00:00Z"
}

Query task status

GET /api/v1/financial-analysis/jobs/{job_id}
Authorization: Bearer {api_key}

Response (when complete):

{
  "id": "job_xxxxx",
  "status": "completed",
  "overall_risk_level": "medium",
  "rule_results": [
    {
      "rule_id": "revenue_authenticity",
      "display_name_zh": "收入真实性",
      "display_name_en": "Revenue Authenticity",
      "rule_category": "收入质量",
      "risk_level": "high",
      "conclusion_zh": "...",
      "evidence": ["..."]
    }
  ]
}

status Values:pending → parsing → chunking → extracting → analyzing → completed / failed

Query rule list

GET /api/v1/financial-analysis/rules
Authorization: Bearer {api_key}

---

Call limits

• Free account: A total of 100 call credits per API Key
• Each PDF upload consumes 1 credit
• PDF file maximum 100MB
• Analysis takes 2-8 minutes; if it times out, please retry

---

Error handling

Error code	Meaning	Handling method
400	Parameter error or non-PDF file	Check the file format and request parameters
401	Invalid API Key or permission not enabled	Check CLAWSHIRE_API_KEY, and enable financial analysis permission in the console
413	File too large	PDF must not exceed 100MB
500	Server error	Retry later, or visit clawshire.cn to check service status