# G-Prophet AI Skills 文档

> 面向 AI 智能体的市场数据分析与量化研究接入

## 概述

G-Prophet 是一个可审计的量化市场研究平台，将市场数据与模型输出整理为可复核的研究记录。它由英国私人有限公司 GPROPHET LIMITED 运营（公司编号 16777200，成立于 2025 年 10 月 10 日）。外部 API 提供市场数据、量化模型推演、不确定性范围、技术指标、多模型比较和异步研究报告。公开市场代码为 US、CN、HK、JP、KR、CRYPTO、UK、CA、DE 和 IN；具体接口与标的覆盖因市场而异。

## 基础信息

| 项目 | 说明 |
|------|------|
| API 基础地址 | `https://www.gprophet.com/api/external/v1` |
| 认证方式 | 付费端点和账户端点使用 `X-API-Key`；公开 `/health`、`/info` 无需 Key |
| Key 格式 | `gp_sk_` 前缀（如 `gp_sk_live_a1b2c3...`） |
| 响应格式 | JSON |
| 计费方式 | 付费操作按积分计费；健康检查、元信息、余额、用量、预检和任务轮询均为 0 积分 |

## 认证

付费操作、账户端点、认证健康检查、账户预检和任务轮询需要 API Key；公开 `GET /health` 与 `GET /info` 无需 Key：

```
X-API-Key: gp_sk_live_your_api_key_here
```

API Key 可在 G-Prophet 平台的「设置 → API Key 管理」页面创建。

### 安全建议

- 将 API Key 存储在环境变量（`GPROPHET_API_KEY`）中，不要硬编码在代码里
- 开发和测试时使用受限范围的 Key
- 定期在 https://www.gprophet.com/dashboard 监控用量和计费
- 定期轮换 Key，发现泄露时立即撤销
- 切勿将 API Key 提交到版本控制或公开分享

## 速率限制

付费操作和认证任务轮询受到按 Key 的速率限制（固定窗口，按分钟计）。

| 响应头 | 说明 |
|--------|------|
| `X-RateLimit-Limit` | 每分钟允许的最大请求数 |
| `X-RateLimit-Remaining` | 当前窗口内剩余请求数 |
| `X-RateLimit-Reset` | 速率限制窗口重置时刻的 Unix 时间戳 |

默认限制为每个 API Key **每分钟 60 次请求**。超出时返回 HTTP 429：

```json
{
  "success": false,
  "data": null,
  "metadata": {
    "request_id": "req_rate_limit"
  },
  "error": {
    "code": "RATE_LIMITED",
    "message": "Rate limit exceeded. Max 60 requests per minute.",
    "details": {
      "limit_per_minute": 60,
      "retry_after_seconds": 45,
      "retryable": true
    }
  }
}
```

响应中包含 `Retry-After` 头，指示需要等待的秒数。

## 配额管理

每个 API Key 可配置每日和每月调用配额。配额 = 0 表示不限制。

超出配额时返回 HTTP 429：

```json
{
  "success": false,
  "error": {
    "code": "QUOTA_EXCEEDED",
    "message": "Daily quota exceeded (100/100)",
    "details": {
      "resolution": "Upgrade your plan or wait for quota reset.",
      "retryable": false
    }
  }
}
```

通过 0 积分的 `GET /account/balance` 查看当前配额使用情况。`QUOTA_EXCEEDED` 不是瞬时的分钟级限流；配额重置或套餐变更前不要重试。

## 统一响应格式

### 成功响应

```json
{
  "success": true,
  "data": {},
  "metadata": {
    "request_id": "req_abc123",
    "timestamp": "2026-02-18T10:30:00Z",
    "processing_time_ms": 1250,
    "api_version": "v1"
  },
  "error": null
}
```

### 错误响应

错误返回对应的 HTTP 状态码（400、401、402、403、404、422、429、500、503）及 JSON 响应体：

```json
{
  "success": false,
  "data": null,
  "metadata": {},
  "error": {
    "code": "SYMBOL_NOT_FOUND",
    "message": "Stock symbol 'XXXXX' not found",
    "details": {}
  }
}
```

### 积分不足响应 (402)

积分不足时，API 返回详细的 402 响应，包含可操作的引导信息：

```json
{
  "success": false,
  "error": {
    "code": "INSUFFICIENT_POINTS",
    "message": "Insufficient points. Required: 20, available: 5.",
    "details": {
      "required": 20,
      "available": 5,
      "shortage": 15,
      "retryable": false,
      "resolution": {
        "actions": [
          { "action": "register", "url": "https://www.gprophet.com/register" },
          { "action": "recharge", "url": "https://www.gprophet.com/membership" },
          { "action": "subscribe", "url": "https://www.gprophet.com/membership" }
        ]
      }
    }
  }
}
```

收到 `INSUFFICIENT_POINTS` 后不要重复同一付费调用。先补充积分，再通过 0 积分的余额端点或 SDK/MCP 预检工具重新检查。预检不会预留积分或速率限制槽位，因此调用方仍必须处理随后可能出现的 402。

## 积分消耗

| Skill | 端点 | 积分/次 |
|-------|------|---------|
| 逐日模型参考路径 | `POST /predictions/predict` | CN 10；US/HK/JP/KR/CRYPTO/UK/CA/DE/IN 20 |
| 算法对比 | `POST /predictions/compare` | 单次模型推演积分 × 算法数量 |
| 行情报价 | `GET /market-data/quote` | 5 |
| 历史K线 | `GET /market-data/history` | 5 |
| 股票搜索 | `GET /market-data/search` | 5 |
| 批量报价 | `POST /market-data/batch-quote` | 5 × 股票数量 |
| 技术分析 | `POST /technical/analyze` | 5 |
| 恐慌贪婪指数 | `GET /sentiment/fear-greed` | 5 |
| 市场概览 | `GET /sentiment/market-overview` | 5 |
| AI 辅助研究报告 | `POST /analysis/stock` | 58 |
| 多因子研究复盘 | `POST /analysis/comprehensive` | 150 |
| 任务轮询 | `GET /analysis/task/{task_id}` | 0（免费） |
| 账户余额 | `GET /account/balance` | 0（免费） |
| 用量统计 | `GET /account/usage` | 0（免费） |
| API 信息 | `GET /info` | 0（免费） |
| 公开健康检查 | `GET /health` | 0（免费） |
| 认证健康检查 | `GET /health/auth` | 0（免费） |
| 模型推演就绪检查 | `GET /predictions/health` | 0（免费） |

---

## Skill 1: 逐日模型参考路径

生成用于研究的逐日模型参考路径与不确定性范围。该路径不是未来真实 OHLCV，也不是交易指令。支持 G-Prophet2026V1、G-Prophet2026V2（仅 CN/A股）、LSTM、Transformer 等多种算法。

### POST /predictions/predict

**请求参数（JSON Body）：**

| 参数 | 类型 | 必填 | 默认值 | 说明 |
|------|------|------|--------|------|
| symbol | string | ✅ | - | 股票/币种代码（如 AAPL, 600519, BTCUSDT） |
| market | string | ✅ | - | 市场代码：`US`, `CN`, `HK`, `JP`, `KR`, `CRYPTO`, `UK`, `CA`, `DE`, `IN` |
| days | integer | 否 | 7 | 推演天数，范围 1-30 |
| algorithm | string | 否 | auto | 算法：`auto`, `gprophet2026v1`, `gprophet2026v2`（仅 CN）, `lstm`, `transformer`, `random_forest`, `ensemble` |

**请求示例：**

```bash
curl -X POST "https://www.gprophet.com/api/external/v1/predictions/predict" \
  -H "X-API-Key: gp_sk_live_your_key" \
  -H "Content-Type: application/json" \
  -d '{"symbol": "AAPL", "market": "US", "days": 2, "algorithm": "auto"}'
```

**响应示例：**

```json
{
  "success": true,
  "data": {
    "symbol": "AAPL",
    "market": "US",
    "currency": "USD",
    "timezone": "America/New_York",
    "current_price": 185.50,
    "predicted_price": 190.25,
    "change_percent": 2.56,
    "direction": "up",
    "confidence": 0.78,
    "prediction_days": 2,
    "algorithm_used": "gprophet2026v1",
    "model_reference_path": {
      "schema_version": "1.0",
      "interval": "1d",
      "date_semantics": "market_local_trading_date",
      "requested_points": 2,
      "point_count": 2,
      "status": "complete",
      "uncertainty": {
        "kind": "model_uncertainty_range",
        "method": "model_percentile",
        "confidence_level": 0.78,
        "confidence_level_semantics": "model_reported_score_not_nominal_coverage",
        "complete": true
      },
      "points": [
        {"step": 1, "date": "2026-08-04", "model_reference_price": 187.10, "uncertainty_lower": 181.40, "uncertainty_upper": 191.03},
        {"step": 2, "date": "2026-08-05", "model_reference_price": 190.25, "uncertainty_lower": 182.72, "uncertainty_upper": 195.44}
      ],
      "warnings": []
    },
    "data_quality": {
      "completeness": 1.0,
      "anomaly_count": 82,
      "missing_values": 0,
      "overall_score": 80
    },
    "points_consumed": 20
  }
}
```

`model_reference_path.points` 按市场本地交易日给出逐日模型参考价格；每个点的 `uncertainty_lower` / `uncertainty_upper` 与同一日期直接绑定。`currency` 是报价币种代码，`timezone` 是解释这些日期的 IANA 市场时区。`status` 可为 `complete`、`partial` 或 `unavailable`；区间不可用或数据不完整时边界为 `null`，并通过 `uncertainty.complete` 与 `warnings` 明确说明。

`uncertainty.confidence_level` 是原模型上报评分；`confidence_level_semantics` 固定为 `model_reported_score_not_nominal_coverage`，明确它不是名义覆盖概率。不得把它按“95% 置信区间”等经过校准的统计区间解读。这些区间也不是买卖指令。路径点不是未来真实 OHLCV；如需历史真实 OHLCV，请另调 `GET /market-data/history`。`POST /predictions/compare` 当前只返回各算法的摘要结果，不返回逐算法 `model_reference_path`。

### POST /predictions/compare

多算法对比模型推演，顶层返回 `currency`、`timezone` 及各算法摘要和对照结果；当前不返回各算法的逐日参考路径。积分消耗 = 单次模型推演积分 × 算法数量。

**请求参数（JSON Body）：**

| 参数 | 类型 | 必填 | 默认值 | 说明 |
|------|------|------|--------|------|
| symbol | string | ✅ | - | 股票/币种代码 |
| market | string | ✅ | - | 市场代码：`US`, `CN`, `HK`, `JP`, `KR`, `CRYPTO`, `UK`, `CA`, `DE`, `IN` |
| days | integer | 否 | 5 | 推演天数，范围 1-30 |
| algorithms | string[] | 否 | CN: ["gprophet2026v2","gprophet2026v1","lstm","transformer","ensemble"]; 其他市场: ["gprophet2026v1","lstm","transformer","ensemble"] | 算法列表，最多 6 个。`gprophet2026v2` 仅支持 CN。 |

**请求示例：**

```bash
curl -X POST "https://www.gprophet.com/api/external/v1/predictions/compare" \
  -H "X-API-Key: gp_sk_live_your_key" \
  -H "Content-Type: application/json" \
  -d '{"symbol": "600519", "market": "CN", "days": 5, "algorithms": ["gprophet2026v2", "gprophet2026v1", "lstm"]}'
```

**响应示例：**

```json
{
  "success": true,
  "data": {
    "symbol": "600519",
    "name": "贵州茅台",
    "market": "CN",
    "currency": "CNY",
    "timezone": "Asia/Shanghai",
    "current_price": 1680.00,
    "prediction_days": 5,
    "results": [
      {
        "algorithm": "gprophet2026v2",
        "predicted_price": 1728.40,
        "change_percent": 2.88,
        "direction": "up",
        "confidence": 0.84,
        "success": true
      },
      {
        "algorithm": "gprophet2026v1",
        "predicted_price": 1720.50,
        "change_percent": 2.41,
        "direction": "up",
        "confidence": 0.82,
        "success": true
      },
      {
        "algorithm": "lstm",
        "predicted_price": 1695.30,
        "change_percent": 0.91,
        "direction": "up",
        "confidence": 0.71,
        "success": true
      }
    ],
    "best_algorithm": "gprophet2026v2",
    "consensus_direction": "up",
    "average_predicted_price": 1714.73,
    "points_consumed": 30
  }
}
```

---

## Skill 2: 市场数据查询

获取最近可用报价、历史观测 OHLCV、标的搜索和批量报价。每次调用消耗 5 积分（批量 = 5 × 数量）。

### GET /market-data/quote

获取最近可用报价。

**查询参数：**

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| symbol | string | ✅ | 股票/币种代码 |
| market | string | ✅ | 市场代码：`US`, `CN`, `HK`, `JP`, `KR`, `CRYPTO`, `UK`, `CA`, `DE`, `IN` |

**请求示例：**

```bash
curl "https://www.gprophet.com/api/external/v1/market-data/quote?symbol=AAPL&market=US" \
  -H "X-API-Key: gp_sk_live_your_key"
```

**响应示例：**

```json
{
  "success": true,
  "data": {
    "symbol": "AAPL",
    "market": "US",
    "currency": "USD",
    "timezone": "America/New_York",
    "name": "Apple Inc.",
    "price": 185.50,
    "open": 183.90,
    "high": 186.80,
    "low": 183.20,
    "volume": 52340000,
    "previous_close": 183.20,
    "change": 2.30,
    "change_percent": 1.26,
    "points_consumed": 5
  }
}
```

`currency` 是报价币种，`timezone` 是解释该市场日期与行情时间的 IANA 时区。

### GET /market-data/history

获取历史 K 线数据（OHLCV）。

**查询参数：**

| 参数 | 类型 | 必填 | 默认值 | 说明 |
|------|------|------|--------|------|
| symbol | string | ✅ | - | 股票/币种代码 |
| market | string | ✅ | - | 市场代码：`US`, `CN`, `HK`, `JP`, `KR`, `CRYPTO`, `UK`, `CA`, `DE`, `IN` |
| period | string | 否 | 3m | 时间范围：`1w`, `1m`, `3m`, `6m`, `1y`, `2y` |

**请求示例：**

```bash
curl "https://www.gprophet.com/api/external/v1/market-data/history?symbol=AAPL&market=US&period=3m" \
  -H "X-API-Key: gp_sk_live_your_key"
```

**响应示例：**

```json
{
  "success": true,
  "data": {
    "symbol": "AAPL",
    "market": "US",
    "currency": "USD",
    "timezone": "America/New_York",
    "period": "3m",
    "data_points": 63,
    "history": [
      {
        "date": "2025-12-01",
        "open": 178.50,
        "high": 180.20,
        "low": 177.80,
        "close": 179.90,
        "volume": 48500000
      }
    ],
    "points_consumed": 5
  }
}
```

历史 OHLCV 是已观测行情；其中 `date` 按响应的 `timezone` 解释。

### GET /market-data/search

搜索股票/加密货币。

**查询参数：**

| 参数 | 类型 | 必填 | 默认值 | 说明 |
|------|------|------|--------|------|
| keyword | string | ✅ | - | 搜索关键词 |
| market | string | 否 | US | 市场代码：`US`, `CN`, `HK`, `JP`, `KR`, `CRYPTO`, `UK`, `CA`, `DE`, `IN` |
| limit | integer | 否 | 10 | 返回数量，范围 1-50 |

**请求示例：**

```bash
curl "https://www.gprophet.com/api/external/v1/market-data/search?keyword=apple&market=US&limit=5" \
  -H "X-API-Key: gp_sk_live_your_key"
```

搜索响应顶层同时返回 `currency` 与 `timezone`，用于解释该市场的代码与后续行情数据。

### POST /market-data/batch-quote

批量获取多个股票/加密货币的最近可用报价。最多 20 个标的。积分消耗 = 5 × 标的数量。

**请求参数（JSON Body）：**

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| symbols | string[] | ✅ | 股票/币种代码列表（最多 20 个） |
| market | string | ✅ | 市场代码：`US`, `CN`, `HK`, `JP`, `KR`, `CRYPTO`, `UK`, `CA`, `DE`, `IN` |

**请求示例：**

```bash
curl -X POST "https://www.gprophet.com/api/external/v1/market-data/batch-quote" \
  -H "X-API-Key: gp_sk_live_your_key" \
  -H "Content-Type: application/json" \
  -d '{"symbols": ["AAPL", "TSLA", "GOOGL"], "market": "US"}'
```

**响应示例：**

```json
{
  "success": true,
  "data": {
    "market": "US",
    "currency": "USD",
    "timezone": "America/New_York",
    "count": 3,
    "successful": 3,
    "results": [
      {
        "symbol": "AAPL",
        "name": "Apple Inc.",
        "success": true,
        "price": 185.50,
        "change": 2.30,
        "change_percent": 1.26
      },
      {
        "symbol": "TSLA",
        "name": "Tesla Inc.",
        "success": true,
        "price": 245.00,
        "change": -3.20,
        "change_percent": -1.29
      },
      {
        "symbol": "GOOGL",
        "name": "Alphabet Inc.",
        "success": true,
        "price": 142.80,
        "change": 1.10,
        "change_percent": 0.78
      }
    ],
    "points_consumed": 15
  }
}
```

---

## Skill 3: 技术指标分析

对指定股票计算全套技术指标并生成指标提示。每次调用消耗 5 积分。

### POST /technical/analyze

**请求参数（JSON Body）：**

| 参数 | 类型 | 必填 | 默认值 | 说明 |
|------|------|------|--------|------|
| symbol | string | ✅ | - | 股票/币种代码 |
| market | string | ✅ | - | 市场代码：`US`, `CN`, `HK`, `JP`, `KR`, `CRYPTO`, `UK`, `CA`, `DE`, `IN` |
| indicators | string[] | 否 | ["rsi","macd","bollinger","kdj"] | 指标列表：`rsi`, `macd`, `bollinger`, `kdj`, `sma`, `ema` |

原始 HTTP 端点默认请求四种指标。Python SDK 0.2.0 与随附 MCP 服务在省略 `indicators` 时会显式请求全部六种指标，积分仍为 5。

**请求示例：**

```bash
curl -X POST "https://www.gprophet.com/api/external/v1/technical/analyze" \
  -H "X-API-Key: gp_sk_live_your_key" \
  -H "Content-Type: application/json" \
  -d '{"symbol": "AAPL", "market": "US", "indicators": ["rsi", "macd", "bollinger", "kdj"]}'
```

**响应示例：**

```json
{
  "success": true,
  "data": {
    "symbol": "AAPL",
    "market": "US",
    "currency": "USD",
    "timezone": "America/New_York",
    "current_price": 185.50,
    "indicators": {
      "rsi_14": { "value": 55.3, "signal": "neutral" },
      "macd": { "macd": 1.25, "signal": 0.98, "histogram": 0.27, "signal_type": "bullish" },
      "bollinger": { "upper": 192.0, "middle": 185.0, "lower": 178.0, "position": 0.54 },
      "kdj": { "k": 65.2, "d": 58.7, "j": 78.2 }
    },
    "signals": [
      { "type": "bullish", "indicator": "MACD" },
      { "type": "neutral", "indicator": "RSI" }
    ],
    "overall_signal": "bullish",
    "signal_strength": 0.5,
    "research_disclaimer": "signals and overall_signal are technical indicator observations, not trading instructions or investment advice.",
    "points_consumed": 5
  }
}
```

---

## Skill 4: 市场情绪分析

获取市场情绪数据，包括恐慌贪婪指数和市场综合概览。每次调用消耗 5 积分。

### GET /sentiment/fear-greed

获取加密货币市场恐慌贪婪指数。

**查询参数：**

| 参数 | 类型 | 必填 | 默认值 | 说明 |
|------|------|------|--------|------|
| days | integer | 否 | 1 | 历史天数，1=仅当前值，范围 1-365 |

**请求示例：**

```bash
curl "https://www.gprophet.com/api/external/v1/sentiment/fear-greed?days=1" \
  -H "X-API-Key: gp_sk_live_your_key"
```

**响应示例：**

```json
{
  "success": true,
  "data": {
    "value": 72,
    "classification": "greed",
    "previous_value": 68,
    "change": 4,
    "points_consumed": 5
  }
}
```

### GET /sentiment/market-overview

获取市场综合概览（涨跌家数、热门板块、主要指数等）。

**查询参数：**

| 参数 | 类型 | 必填 | 默认值 | 说明 |
|------|------|------|--------|------|
| market | string | 否 | CN | 市场代码：`CN`, `US` |

**请求示例：**

```bash
curl "https://www.gprophet.com/api/external/v1/sentiment/market-overview?market=CN" \
  -H "X-API-Key: gp_sk_live_your_key"
```

---

## Skill 5: AI 辅助研究报告（异步）

生成单一标的的 AI 辅助研究报告，消耗 58 积分，支持全部十个公开市场。

> ⚠️ **异步模式**：分析通常耗时 15-60 秒，此接口采用异步模式。
> 1. `POST /analysis/stock` → 立即返回 `task_id`
> 2. `GET /analysis/task/{task_id}` → 轮询任务状态，`status=completed` 时取结果
>
> 建议轮询间隔：5 秒，最长等待：5 分钟。

### POST /analysis/stock

提交个股分析任务，立即返回任务 ID。

**请求参数（JSON Body）：**

| 参数 | 类型 | 必填 | 默认值 | 说明 |
|------|------|------|--------|------|
| symbol | string | ✅ | - | 股票/币种代码 |
| market | string | ✅ | - | 市场代码：`US`, `CN`, `HK`, `JP`, `KR`, `CRYPTO`, `UK`, `CA`, `DE`, `IN` |
| locale | string | 否 | zh-CN | 分析报告语言：`zh-CN`, `en-US` |
| callback_url | string | 否 | - | 公开可达的 HTTPS Webhook；禁止 localhost、私网地址和内部主机名 |

**请求示例：**

```bash
curl -X POST "https://www.gprophet.com/api/external/v1/analysis/stock" \
  -H "X-API-Key: gp_sk_live_your_key" \
  -H "Content-Type: application/json" \
  -d '{"symbol": "AAPL", "market": "US", "locale": "en-US"}'
```

**响应示例（立即返回）：**

```json
{
  "success": true,
  "data": {
    "task_id": "task_abc123def456",
    "symbol": "AAPL",
    "market": "US",
    "status": "pending",
    "points_consumed": 58,
    "poll_url": "/api/external/v1/analysis/task/task_abc123def456",
    "callback_url": null,
    "message": "Stock analysis started. Poll the task URL every 5 seconds for results."
  }
}
```

---

## Skill 6: 多因子研究复盘（异步）

多智能体从技术面、基本面、资金面、情绪面和宏观环境开展多因子研究复盘，消耗 150 积分，支持全部十个公开市场。

> ⚠️ **异步模式**：多因子研究复盘通常耗时 30-120 秒，因此此接口采用异步模式。
> 1. `POST /analysis/comprehensive` → 立即返回 `task_id`
> 2. `GET /analysis/task/{task_id}` → 轮询任务状态，`status=completed` 时取结果
>
> 建议轮询间隔：5 秒，最长等待：5 分钟。

### POST /analysis/comprehensive

提交多因子研究复盘任务，立即返回任务 ID。

**请求参数（JSON Body）：**

| 参数 | 类型 | 必填 | 默认值 | 说明 |
|------|------|------|--------|------|
| symbol | string | ✅ | - | 股票/币种代码 |
| market | string | ✅ | - | 市场代码：`US`, `CN`, `HK`, `JP`, `KR`, `CRYPTO`, `UK`, `CA`, `DE`, `IN` |
| locale | string | 否 | zh-CN | 分析报告语言：`zh-CN`, `en-US` |
| callback_url | string | 否 | - | 公开可达的 HTTPS Webhook；禁止 localhost、私网地址和内部主机名 |

**请求示例：**

```bash
curl -X POST "https://www.gprophet.com/api/external/v1/analysis/comprehensive" \
  -H "X-API-Key: gp_sk_live_your_key" \
  -H "Content-Type: application/json" \
  -d '{"symbol": "AAPL", "market": "US", "locale": "zh-CN"}'
```

**响应示例（立即返回）：**

```json
{
  "success": true,
  "data": {
    "task_id": "task_abc123def456",
    "symbol": "AAPL",
    "market": "US",
    "status": "pending",
    "points_consumed": 150,
    "poll_url": "/api/external/v1/analysis/task/task_abc123def456",
    "callback_url": null,
    "message": "Analysis started. Poll the task URL every 5 seconds for results."
  }
}
```

### Webhook 回调

`/analysis/stock` 和 `/analysis/comprehensive` 均支持可选的 `callback_url` 参数。该地址必须使用 HTTPS，并且只能解析到公开可达的目标；禁止 localhost、回环地址、链路本地地址、私网地址、内部主机名，以及重定向到这些目标。提供后，API 会在任务完成或失败时向该 URL POST 结果：

**回调载荷（成功）：**

```json
{
  "task_id": "task_abc123def456",
  "status": "completed",
  "result": {}
}
```

**回调载荷（失败）：**

```json
{
  "task_id": "task_abc123def456",
  "status": "failed",
  "error": "Analysis service timeout"
}
```

### GET /analysis/task/{task_id}

轮询分析任务状态和结果。

**路径参数：**

| 参数 | 类型 | 说明 |
|------|------|------|
| task_id | string | 由分析端点返回的任务 ID |

**请求示例：**

```bash
curl "https://www.gprophet.com/api/external/v1/analysis/task/task_abc123def456" \
  -H "X-API-Key: gp_sk_live_your_key"
```

**状态流转：** `pending` → `running`（progress 0-100）→ `completed` / `failed`

**响应示例（进行中）：**

```json
{
  "success": true,
  "data": {
    "task_id": "task_abc123def456",
    "status": "running",
    "progress": 45,
    "message": "Analyzing fundamental data...",
    "result": null,
    "error": null
  }
}
```

**响应示例（完成）：**

```json
{
  "success": true,
  "data": {
    "task_id": "task_abc123def456",
    "status": "completed",
    "progress": 100,
    "message": "Analysis completed",
    "result": {
      "symbol": "AAPL",
      "asset_type": "stock_us",
      "analysis": {
        "overall_rating": "bullish",
        "confidence": 0.75,
        "agents": {
          "technical": {
            "rating": "bullish",
            "confidence": 0.80,
            "key_points": ["MACD金叉", "站上20日均线"],
            "summary": "技术面整体偏多..."
          },
          "fundamental": {
            "rating": "neutral",
            "confidence": 0.65,
            "key_points": ["PE合理", "营收增长放缓"],
            "summary": "基本面中性..."
          },
          "capital_flow": {
            "rating": "bullish",
            "confidence": 0.70,
            "key_points": ["主力资金净流入"],
            "summary": "资金面偏多..."
          },
          "sentiment": {
            "rating": "neutral",
            "confidence": 0.60,
            "key_points": ["市场情绪平稳"],
            "summary": "情绪面中性..."
          },
          "macro": {
            "rating": "cautious",
            "confidence": 0.55,
            "key_points": ["加息预期", "地缘风险"],
            "summary": "宏观环境偏谨慎..."
          }
        },
        "research_observation": "短期模型偏上行，需关注波动与宏观风险",
        "risk_level": "medium"
      }
    },
    "error": null
  }
}
```

**响应示例（失败）：**

```json
{
  "success": true,
  "data": {
    "task_id": "task_abc123def456",
    "status": "failed",
    "progress": 100,
    "message": "Analysis service timeout",
    "result": null,
    "error": "Analysis service timeout"
  }
}
```

---

## 账户端点

### GET /account/balance

查询当前 API Key 的积分余额和配额使用情况。免费，不消耗积分。

**请求示例：**

```bash
curl "https://www.gprophet.com/api/external/v1/account/balance" \
  -H "X-API-Key: gp_sk_live_your_key"
```

**响应示例：**

```json
{
  "success": true,
  "data": {
    "available_points": 1250,
    "key_name": "My Trading Bot",
    "key_prefix": "gp_sk_abc",
    "scopes": ["predictions", "market_data", "technical", "sentiment", "analysis"],
    "rate_limit_per_minute": 60,
    "daily_quota": 1000,
    "daily_used": 42,
    "monthly_quota": 0,
    "monthly_used": 856
  }
}
```

### GET /account/usage

查询当前 API Key 的调用历史统计。免费，不消耗积分。

**查询参数：**

| 参数 | 类型 | 必填 | 默认值 | 说明 |
|------|------|------|--------|------|
| days | integer | 否 | 7 | 查询天数，范围 1-90 |

**请求示例：**

```bash
curl "https://www.gprophet.com/api/external/v1/account/usage?days=7" \
  -H "X-API-Key: gp_sk_live_your_key"
```

**响应示例：**

```json
{
  "success": true,
  "data": {
    "key_prefix": "gp_sk_abc",
    "period_days": 7,
    "daily": [
      {
        "date": "2026-03-09",
        "total_calls": 85,
        "success_calls": 82,
        "avg_response_ms": 1250
      }
    ],
    "by_endpoint": [
      { "endpoint": "/api/external/v1/predictions/predict", "calls": 45 },
      { "endpoint": "/api/external/v1/market-data/quote", "calls": 30 }
    ]
  }
}
```

### GET /info

获取公开 API 元信息：支持的市场、市场详情、币种、IANA 时区、算法、价格和端点支持情况。免费、无需 API Key 且不消耗积分。

**请求示例：**

```bash
curl "https://www.gprophet.com/api/external/v1/info"
```

**响应字段要点：**

```json
{
  "success": true,
  "data": {
    "supported_markets": ["US", "CN", "HK", "JP", "KR", "CRYPTO", "UK", "CA", "DE", "IN"],
    "market_details": [
      {
        "code": "UK",
        "name": "UK Stocks",
        "currency": "GBP",
        "timezone": "Europe/London",
        "ticker_format": "Use market=UK. LSE-style symbols accepted with normalization; GB/LSE are not market codes.",
        "examples": ["HSBA.LON", "TSCO.LON", "BP.LON", "SHEL.LON", "AZN.LON"],
        "endpoint_support": ["predictions", "market_data", "technical", "stock_analysis", "comprehensive_analysis"]
      },
      {
        "code": "JP",
        "name": "Japan Stocks",
        "currency": "JPY",
        "timezone": "Asia/Tokyo",
        "ticker_format": "4-5 character TSE symbol; bare symbols and .T suffix are accepted.",
        "examples": ["7203", "7203.T", "130A.T"],
        "endpoint_support": ["predictions", "market_data", "technical", "stock_analysis", "comprehensive_analysis"]
      },
      {
        "code": "KR",
        "name": "Korea Stocks",
        "currency": "KRW",
        "timezone": "Asia/Seoul",
        "ticker_format": "6-digit KRX symbol; bare symbols plus .KS and .KQ suffixes are accepted.",
        "examples": ["005930", "005930.KS", "035420.KQ"],
        "endpoint_support": ["predictions", "market_data", "technical", "stock_analysis", "comprehensive_analysis"]
      }
    ],
    "market_extension_rule": {
      "parameter": "market",
      "description": "Call the same endpoint paths with market=<market code>."
    }
  }
}
```

AI/SDK/MCP 集成应优先读取 `GET /info` 的 `supported_markets` 与 `market_details`，不要硬编码旧市场列表。

---

## 健康检查

三类健康检查均为 0 积分操作，且不运行模型：

| 端点 | 认证 | 用途 |
|------|------|------|
| `GET /health` | 无需 API Key | 确认请求已到达 G-Prophet 源站 |
| `GET /health/auth` | `X-API-Key` | 验证 Key 和所属账户，并报告权限、配额计数器和积分 |
| `GET /predictions/health?market=US` | `X-API-Key` + predictions 权限 | 检查 Key、权限、市场及一次模型运行所需积分 |

这些端点不会预留积分或速率限制槽位。返回的配额计数器仅供参考；调用方仍须处理随后可能出现的 402、403 或 429。

---

## 错误码

| 错误码 | HTTP 状态码 | 说明 |
|--------|------------|------|
| MISSING_API_KEY | 401 | 缺少 X-API-Key 请求头 |
| INVALID_KEY_FORMAT | 401 | API Key 格式错误（必须以 gp_sk_ 开头） |
| INVALID_API_KEY | 401 | API Key 无效 |
| API_KEY_DISABLED | 403 | API Key 已被禁用 |
| API_KEY_EXPIRED | 403 | API Key 已过期 |
| INSUFFICIENT_SCOPE | 403 | API Key 无此 Skill 的访问权限 |
| INSUFFICIENT_POINTS | 402 | 积分不足；`retryable: false`，补充积分前不要再次发起付费调用 |
| POINTS_DEDUCTION_FAILED | 500 | 积分扣除失败 |
| OWNER_NOT_FOUND | 403 | API Key 所属用户不存在 |
| RATE_LIMITED | 429 | 请求频率超过每分钟限制 |
| QUOTA_EXCEEDED | 429 | 每日或每月调用配额已用尽 |
| INVALID_MARKET | 422 | 不支持的市场代码 |
| UNSUPPORTED_MARKET | 422 | 该端点不支持此市场 |
| UNSUPPORTED_ALGORITHM_MARKET | 422 | 所选算法不支持指定市场；G-Prophet2026V2 仅支持 CN/A股 |
| SYMBOL_NOT_FOUND | 422 | 股票/币种代码未找到 |
| NO_DATA | 422 | 无法获取数据 |
| VALIDATION_ERROR | 422 | 请求参数校验失败 |
| TOO_MANY_ALGORITHMS | 400 | 算法数量超过上限（最多 6 个） |
| PREDICTION_FAILED | 500 | 模型分析服务异常 |
| TASK_NOT_FOUND | 404 | 异步任务不存在或已过期 |
| FORBIDDEN | 403 | 无权访问该资源（如查询他人的任务） |
| DATA_UNAVAILABLE | 503 | 数据源暂不可用 |
| DATA_SOURCE_UNAVAILABLE | 503 | 历史行情数据暂不可用 |
| INTERNAL_ERROR | 500 | 内部服务错误 |

不能因为缺少 `retryable` 字段就认定请求可以安全重试。尤其是付费请求发生读取超时、发送后连接重置或网关返回无效/非 JSON 响应时，服务端可能已经扣除积分。决定是否再次调用前，应先检查用量、余额或任务状态。

---

## MCP Tools 定义

以下是 MCP（Model Context Protocol）格式的 Tool 定义，可直接用于 Claude、Kiro 等支持 MCP 的智能体：

> **⚠️ AI 智能体注意事项**：这些工具应通过 MCP 协议调用，而非自行构造 HTTP 请求。如果你是没有 MCP 访问权限的 AI 智能体，请使用 Python SDK（`pip install gprophet`）或向基础地址 `https://www.gprophet.com/api/external/v1` 发送 HTTP 请求并携带 `X-API-Key` 请求头。请勿自行猜测或拼凑端点 URL — 务必使用上方文档中记录的精确路径（例如 `POST /predictions/predict`，而非 `/predict` 或 `/api/predict`）。

### gprophet_predict

```json
{
  "name": "gprophet_predict",
  "description": "生成逐日模型参考路径。市场：US、CN、HK、JP、KR、CRYPTO、UK、CA、DE、IN。返回 currency、timezone、model_reference_path 及日期对齐的不确定性上下界；confidence_level 是原模型上报评分，不是名义覆盖概率，不能按校准置信区间解读；路径不是未来真实 OHLCV。G-Prophet2026V2 仅支持 CN/A股。",
  "inputSchema": {
    "type": "object",
    "properties": {
      "symbol": { "type": "string", "description": "Stock/crypto symbol (e.g., AAPL, 600519, BTCUSDT)" },
      "market": { "type": "string", "enum": ["US", "CN", "HK", "JP", "KR", "CRYPTO", "UK", "CA", "DE", "IN"], "default": "US" },
      "days": { "type": "integer", "minimum": 1, "maximum": 30, "default": 7 },
      "algorithm": { "type": "string", "enum": ["auto", "gprophet2026v1", "gprophet2026v2", "lstm", "transformer", "random_forest", "ensemble"], "default": "auto" }
    },
    "required": ["symbol"]
  }
}
```

### gprophet_compare

```json
{
  "name": "gprophet_compare",
  "description": "对比 1-6 个模型推演摘要；积分消耗为该市场单次模型推演价格乘以唯一算法数量。",
  "inputSchema": {
    "type": "object",
    "properties": {
      "symbol": { "type": "string" },
      "market": { "type": "string", "enum": ["US", "CN", "HK", "JP", "KR", "CRYPTO", "UK", "CA", "DE", "IN"], "default": "US" },
      "days": { "type": "integer", "minimum": 1, "maximum": 30, "default": 5 },
      "algorithms": { "type": "array", "items": { "type": "string", "enum": ["gprophet2026v1", "gprophet2026v2", "lstm", "transformer", "random_forest", "ensemble"] }, "minItems": 1, "maxItems": 6, "uniqueItems": true }
    },
    "required": ["symbol", "algorithms"]
  }
}
```

### gprophet_quote

```json
{
  "name": "gprophet_quote",
  "description": "获取股票/加密货币的最近可用报价，并返回币种与 IANA 市场时区。",
  "inputSchema": {
    "type": "object",
    "properties": {
      "symbol": { "type": "string", "description": "Stock/crypto symbol" },
      "market": { "type": "string", "enum": ["US", "CN", "HK", "JP", "KR", "CRYPTO", "UK", "CA", "DE", "IN"], "default": "US" }
    },
    "required": ["symbol"]
  }
}
```

### gprophet_batch_quote

```json
{
  "name": "gprophet_batch_quote",
  "description": "批量获取多个标的的最近可用报价（最多 20 个）。积分消耗 = 5 × 标的数量。",
  "inputSchema": {
    "type": "object",
    "properties": {
      "symbols": { "type": "array", "items": { "type": "string" }, "minItems": 1, "maxItems": 20, "uniqueItems": true, "description": "List of 1-20 unique symbols" },
      "market": { "type": "string", "enum": ["US", "CN", "HK", "JP", "KR", "CRYPTO", "UK", "CA", "DE", "IN"], "default": "US" }
    },
    "required": ["symbols"]
  }
}
```

### gprophet_history

```json
{
  "name": "gprophet_history",
  "description": "获取股票/加密货币的历史K线数据（OHLCV），支持多种时间范围。",
  "inputSchema": {
    "type": "object",
    "properties": {
      "symbol": { "type": "string" },
      "market": { "type": "string", "enum": ["US", "CN", "HK", "JP", "KR", "CRYPTO", "UK", "CA", "DE", "IN"], "default": "US" },
      "period": { "type": "string", "enum": ["1w", "1m", "3m", "6m", "1y", "2y"], "default": "3m" }
    },
    "required": ["symbol"]
  }
}
```

### gprophet_search

```json
{
  "name": "gprophet_search",
  "description": "搜索股票/加密货币，根据关键词查找匹配的标的。",
  "inputSchema": {
    "type": "object",
    "properties": {
      "keyword": { "type": "string" },
      "market": { "type": "string", "enum": ["US", "CN", "HK", "JP", "KR", "CRYPTO", "UK", "CA", "DE", "IN"], "default": "US" },
      "limit": { "type": "integer", "minimum": 1, "maximum": 50, "default": 10 }
    },
    "required": ["keyword"]
  }
}
```

### gprophet_technical

```json
{
  "name": "gprophet_technical",
  "description": "对指定股票进行全套技术指标分析，包括 RSI、MACD、布林带、KDJ 等，并生成综合指标提示。",
  "inputSchema": {
    "type": "object",
    "properties": {
      "symbol": { "type": "string" },
      "market": { "type": "string", "enum": ["US", "CN", "HK", "JP", "KR", "CRYPTO", "UK", "CA", "DE", "IN"], "default": "US" },
      "indicators": { "type": "array", "items": { "type": "string", "enum": ["rsi", "macd", "bollinger", "kdj", "sma", "ema"] }, "default": ["rsi", "macd", "bollinger", "kdj", "sma", "ema"] }
    },
    "required": ["symbol"]
  }
}
```

### gprophet_fear_greed

```json
{
  "name": "gprophet_fear_greed",
  "description": "获取加密货币市场恐慌贪婪指数，反映市场情绪状态。",
  "inputSchema": {
    "type": "object",
    "properties": {
      "days": { "type": "integer", "minimum": 1, "maximum": 365, "default": 1 }
    }
  }
}
```

### gprophet_market_overview

```json
{
  "name": "gprophet_market_overview",
  "description": "获取市场综合概览，包括涨跌家数、热门板块、主要指数等。",
  "inputSchema": {
    "type": "object",
    "properties": {
      "market": { "type": "string", "enum": ["CN", "US"], "default": "CN" }
    }
  }
}
```

### gprophet_analyze_stock

```json
{
  "name": "gprophet_analyze_stock",
  "description": "为任一公开市场生成 AI 辅助研究报告（58 积分，异步模式）。返回 task_id，通过 gprophet_task_status 轮询结果；余额状态不确定时先调用免费的 gprophet_preflight。",
  "inputSchema": {
    "type": "object",
    "properties": {
      "symbol": { "type": "string" },
      "market": { "type": "string", "enum": ["US", "CN", "HK", "JP", "KR", "CRYPTO", "UK", "CA", "DE", "IN"], "default": "US" },
      "locale": { "type": "string", "enum": ["zh-CN", "en-US"], "default": "en-US" },
      "callback_url": { "type": "string", "description": "Optional public HTTPS webhook; validated by the tool before the paid request" }
    },
    "required": ["symbol"]
  }
}
```

### gprophet_analyze_comprehensive

```json
{
  "name": "gprophet_analyze_comprehensive",
  "description": "为任一公开市场生成多智能体、多因子研究复盘（150 积分，异步模式）。返回 task_id，通过 gprophet_task_status 轮询结果；余额状态不确定时先调用免费的 gprophet_preflight。",
  "inputSchema": {
    "type": "object",
    "properties": {
      "symbol": { "type": "string" },
      "market": { "type": "string", "enum": ["US", "CN", "HK", "JP", "KR", "CRYPTO", "UK", "CA", "DE", "IN"], "default": "US" },
      "locale": { "type": "string", "enum": ["zh-CN", "en-US"], "default": "en-US" },
      "callback_url": { "type": "string", "description": "Optional public HTTPS webhook; validated by the tool before the paid request" }
    },
    "required": ["symbol"]
  }
}
```

### gprophet_task_status

```json
{
  "name": "gprophet_task_status",
  "description": "轮询异步分析任务状态。建议每 5 秒轮询一次，直到 status 为 completed 或 failed。",
  "inputSchema": {
    "type": "object",
    "properties": {
      "task_id": { "type": "string", "description": "Task ID returned by analysis endpoints" }
    },
    "required": ["task_id"]
  }
}
```

### gprophet_health

```json
{
  "name": "gprophet_health",
  "description": "检查公开 API 是否到达源站，0 积分。",
  "inputSchema": { "type": "object", "properties": {} }
}
```

### gprophet_auth_health

```json
{
  "name": "gprophet_auth_health",
  "description": "验证 Key/账户，并报告权限、配额计数器和积分，0 积分。",
  "inputSchema": { "type": "object", "properties": {} }
}
```

### gprophet_prediction_health

```json
{
  "name": "gprophet_prediction_health",
  "description": "不运行模型，检查模型推演权限、市场及一次调用的积分可用性。",
  "inputSchema": {
    "type": "object",
    "properties": {
      "market": { "type": "string", "enum": ["US", "CN", "HK", "JP", "KR", "CRYPTO", "UK", "CA", "DE", "IN"], "default": "US" }
    }
  }
}
```

### gprophet_balance

```json
{
  "name": "gprophet_balance",
  "description": "查询当前积分余额、配额使用情况和 API Key 信息。免费。",
  "inputSchema": { "type": "object", "properties": {} }
}
```

### gprophet_usage

```json
{
  "name": "gprophet_usage",
  "description": "获取当前 API Key 的用量统计，0 积分。",
  "inputSchema": {
    "type": "object",
    "properties": {
      "days": { "type": "integer", "minimum": 1, "maximum": 90, "default": 7 }
    }
  }
}
```

### gprophet_info

```json
{
  "name": "gprophet_info",
  "description": "获取 API 元信息：支持的市场、报价币种、IANA 时区、算法和积分价格表。免费。",
  "inputSchema": { "type": "object", "properties": {} }
}
```

### gprophet_preflight

```json
{
  "name": "gprophet_preflight",
  "description": "使用最新积分定价和账户余额进行免费预检，检查已知的积分、权限和配额门槛，但不预留积分或速率限制槽位；compare 与 batch_quote 必须传入 count。",
  "inputSchema": {
    "type": "object",
    "properties": {
      "operation": { "type": "string", "enum": ["predict", "compare", "quote", "batch_quote", "history", "search", "technical", "fear_greed", "market_overview", "analyze_stock", "analyze_comprehensive"] },
      "market": { "type": "string", "enum": ["US", "CN", "HK", "JP", "KR", "CRYPTO", "UK", "CA", "DE", "IN"], "default": "US" },
      "count": { "type": "integer", "minimum": 1, "maximum": 20, "description": "Required for compare/batch_quote: exact algorithm or symbol count" }
    },
    "required": ["operation"]
  }
}
```

输入通过 MCP schema 校验后，API 与工具执行失败会以结构化错误返回，并标记 MCP `isError`。Schema 校验失败发生在 handler 运行之前，属于 MCP 协议原生错误，不保证包含工具的结构化 envelope 或 `structuredContent`。请遵循 `error.details.retryable`；遇到 402、配额耗尽、读取超时或无效/非 JSON 网关响应时，不要自动重复付费调用。响应丢失的付费调用可能已经扣除积分。

---

## 调用流程示例

### 典型的模型参考路径调用流程

```
1. 账户状态不确定时，先调用 gprophet_preflight(operation="predict", market=...)
2. 代码不确定时先搜索，并保留响应返回的标准 symbol、name 和 market
3. 调用 gprophet_predict，读取 currency、timezone、model_reference_path.points 及日期对齐的不确定性上下界
4. 可选调用 gprophet_history 和 gprophet_technical 补充历史观测与指标上下文
5. 将结果表述为研究观察，不输出买入/卖出/持有指令
```

### 典型的 AI 辅助研究报告调用流程

```
1. 调用 gprophet_analyze_stock 提交分析任务 → 获得 task_id
2. 每 5 秒调用 gprophet_task_status 轮询
3. 当 status = "completed" 时，从 result 获取分析报告
4. 当 status = "failed" 时，从 error 获取失败原因
```

### 典型的多因子研究复盘调用流程

```
1. 调用 gprophet_analyze_comprehensive 提交分析任务 → 获得 task_id
2. 每 5 秒调用 gprophet_task_status 轮询
3. 当 status = "completed" 时，从 result.analysis 获取完整报告
4. 当 status = "failed" 时，从 error 获取失败原因
```

### Webhook 集成流程

```
1. 调用 POST /analysis/stock 或 /analysis/comprehensive 时传入符合要求、公开可达的 HTTPS callback_url
2. 继续处理其他任务（无需轮询）
3. 任务完成或失败时，收到 POST 到 callback_url 的回调
4. 验证 task_id 并处理结果
```

### 智能体集成建议

- **模型调用前先搜索**：代码不确定时，使用 `gprophet_search`，并保留其返回的标准 `symbol`、`name`、`market`
- **组合上下文**：结合模型参考路径、历史 OHLCV、不确定性、技术指标和市场上下文复盘
- **账户预检**：账户状态不确定时，在付费操作前调用 `gprophet_preflight`；compare 与 batch quote 必须传入准确 `count`
- **批量操作**：使用 `gprophet_batch_quote`，避免逐个发起单标的报价请求
- **错误处理**：遵循 `error.details.retryable`；402、配额耗尽或付费调用状态不明的超时均不得自动重试
- **Webhook**：只使用公开可达的 HTTPS 回调地址；禁止 localhost、私网地址和内部主机名

### Python SDK 0.2.0

核心 SDK 支持 Python 3.8+，MCP extra 需要 Python 3.10+：

```bash
pip install gprophet
pip install "gprophet[mcp]"
```

```python
from gprophet import GProphet, InsufficientPointsError

client = GProphet(api_key="gp_sk_...")
plan = client.preflight("predict", market="US")  # 0 积分，不预留资源。

if plan["ready"]:
    try:
        result = client.predict("AAPL", market="US", days=7)
        print(result["currency"], result["timezone"])
        print(result["model_reference_path"]["points"])
    except InsufficientPointsError as exc:
        print(exc.to_dict())  # 预检后账户状态仍可能变化。
```

SDK/MCP 的技术分析调用在省略 `indicators` 时会请求全部六种受支持指标。公开 HTTP `GET /health` 与 `GET /info` 无需 Key；账户检查及所有付费工具需要 Key。预检使用最新积分定价检查已知的积分、权限与配额门槛，但不预留积分或速率限制槽位。Python SDK 使用 `wait=True` 时，任务创建后的轮询失败会保留原 `task_id`；只能继续调用 `client.task_status(task_id)`，不得自动重新提交付费分析。

---

## 支持的市场代码

| 代码 | 市场 | 代码格式 | 示例代码 |
|------|------|----------|----------|
| US | 美股 | 英文字母股票代码 | AAPL, TSLA, GOOGL, MSFT |
| CN | A股（中国大陆） | 6位数字。6开头=上交所，0/3开头=深交所 | 600519, 000001, 300750 |
| HK | 港股 | 数字代码支持裸数字、4位补零代码或 `.HK` 后缀；系统会统一归一化 | 700, 0700, 700.HK, 9988 |
| JP | 日本股票 | 4-5 位东京证券交易所代码；接受裸代码或 `.T` 后缀 | 7203, 7203.T, 130A.T |
| KR | 韩国股票 | 6 位韩国交易所代码；接受裸代码、`.KS` 或 `.KQ` 后缀 | 005930, 005930.KS, 035420.KQ |
| CRYPTO | 加密货币 | 交易对代码（以USDT结尾） | BTCUSDT, ETHUSDT, SOLUSDT |
| UK | 英国股市 | 市场代码固定为 `UK`；接受 LSE 风格代码，系统会做常见格式归一化 | HSBA.LON, TSCO.LON, BP.LON, SHEL.LON, AZN.LON |
| CA | 加拿大股市 | 接受 TSX 风格代码，系统会做常见格式归一化 | SHOP.TRT, CNR.TRT, RY.TRT, TD.TRT |
| DE | 德国股市 | 接受 XETRA/德国后缀变体，系统会做常见格式归一化 | SAP.DEX, SIE.DEX, ALV.DEX, MBG.DEX |
| IN | 印度股市 | 接受 NSE/BSE 后缀变体，系统会做常见格式归一化 | RELIANCE.NS, TCS.NS, INFY.NS, HDFCBANK.NS |

## 未来市场扩展规则

- 调用方式固定为同一参数：`market=<市场代码>`。
- AI/SDK/MCP 应优先调用 `GET /info` 读取 `supported_markets` 与 `market_details`，不要硬编码旧市场列表。
- 新市场一旦出现在 `/info.supported_markets`，同类端点按相同路径调用，例如 `GET /market-data/quote?symbol=...&market=XX`。
- 如果端点不支持某市场，返回 `UNSUPPORTED_MARKET` 或 `INVALID_MARKET`；不要改 URL，只调整 `market` 或选择支持该市场的端点。
- 自动调用建议：先调用 `GET /market-data/search`，使用搜索结果返回的标准 `symbol` 再调用 `predict`；如果搜索无结果，不要直接推演，避免浪费积分。
- 港股裸数字可直接传入，例如 `symbol=700&market=HK`；服务会按 `0700` 处理。客户端也可以主动使用 `0700` 或 `700.HK`。
- 日本股票接受 `7203`、`7203.T` 等形式；韩国股票使用 6 位代码，并接受 `.KS` / `.KQ` 后缀，例如 `005930.KS`、`035420.KQ`。
- `UK` 是英国市场的正式 market code，不使用 `GB` 或 `LSE` 作为 market 参数。交易所信息体现在 symbol 后缀中，例如 `HSBA.LON`。
- 国际市场上游可能较慢，客户端 timeout 建议至少 120 秒。付费调用发生读取超时后不要自动重复请求：服务端可能已扣除积分，应先检查用量、余额或任务状态。

> ⚠️ **A股代码注意事项**：
> - A股代码为 **6位数字**，不同前缀代表不同交易所和板块
> - `6xxxxx` = 上海证券交易所（主板/科创板）
> - `0xxxxx` = 深圳证券交易所（主板/中小板）
> - `3xxxxx` = 深圳证券交易所（创业板）
> - 请确保传入正确的6位代码，例如 `600986`（浙文互联）和 `000001`（平安银行）是不同的股票

## 支持的模型算法

| 算法 | 说明 |
|------|------|
| auto | 自动选择最优算法 |
| gprophet2026v1 | G-Prophet2026V1 自研模型 |
| gprophet2026v2 | G-Prophet2026V2 A股模型，仅支持 CN |
| lstm | 长短期记忆网络 |
| transformer | Transformer 模型 |
| random_forest | 随机森林 |
| ensemble | 集成学习（多算法融合） |

