# G-Prophet AI Skills Documentation

> Market data analysis and quantitative research integrations for AI agents

## Overview

G-Prophet is an auditable quantitative market research platform that turns market data and model outputs into reviewable research records. It is operated by GPROPHET LIMITED, a UK private limited company (Company No. 16777200, incorporated 2025-10-10). The external API exposes market data, quantitative model projections, uncertainty ranges, technical indicators, multi-model comparisons, and asynchronous research reports. Current public market codes are US, CN, HK, JP, KR, CRYPTO, UK, CA, DE, and IN; operation and instrument coverage vary by market.

## Basic Information

| Item | Description |
|------|-------------|
| API Base URL | `https://www.gprophet.com/api/external/v1` |
| Authentication | `X-API-Key` for paid and account endpoints; public `/health` and `/info` require no key |
| Key Format | `gp_sk_` prefix (e.g. `gp_sk_live_a1b2c3...`) |
| Response Format | JSON |
| Billing | Points-based for paid operations; health, metadata, balance, usage, preflight, and task polling consume zero points |

## Authentication

Paid operations, account endpoints, authenticated health checks, preflight account checks, and task polling require an API Key. Public `GET /health` and `GET /info` do not require one:

```
X-API-Key: gp_sk_live_your_api_key_here
```

API Keys can be created in the G-Prophet platform under "Settings → API Key Management".

### Security Recommendations

- Store API keys in environment variables (`GPROPHET_API_KEY`), not in code
- Use test/limited-scope keys for development and evaluation
- Monitor usage and billing regularly at https://www.gprophet.com/dashboard
- Rotate keys periodically and revoke compromised keys immediately
- Never commit API keys to version control or share them publicly

## Rate Limiting

Paid operations and authenticated task polling are subject to per-key rate limiting (fixed window, per minute).

| Header | Description |
|--------|-------------|
| `X-RateLimit-Limit` | Maximum requests allowed per minute |
| `X-RateLimit-Remaining` | Remaining requests in current window |
| `X-RateLimit-Reset` | Unix timestamp when the rate-limit window resets |

Default limit is **60 requests per minute** per API Key. When exceeded, the API returns 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
    }
  }
}
```

The response includes a `Retry-After` header indicating how many seconds to wait.

## Quota Management

Each API Key has configurable daily and monthly call quotas. Quota = 0 means unlimited.

When quota is exceeded, the API returns 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
    }
  }
}
```

Check current quota usage via the zero-point `GET /account/balance` endpoint. `QUOTA_EXCEEDED` is not a transient per-minute rate limit; do not retry until the quota resets or the account plan changes.

## Unified Response Format

### Success Response

```json
{
  "success": true,
  "data": {},
  "metadata": {
    "request_id": "req_abc123",
    "timestamp": "2026-02-18T10:30:00Z",
    "processing_time_ms": 1250,
    "api_version": "v1"
  },
  "error": null
}
```

### Error Response

Errors return the appropriate HTTP status code (400, 401, 402, 403, 404, 422, 429, 500, 503) along with a JSON body:

```json
{
  "success": false,
  "data": null,
  "metadata": {},
  "error": {
    "code": "SYMBOL_NOT_FOUND",
    "message": "Stock symbol 'XXXXX' not found",
    "details": {}
  }
}
```

### Insufficient Points Response (402)

When points are insufficient, the API returns a detailed 402 response with actionable guidance:

```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" }
        ]
      }
    }
  }
}
```

Do not retry the same paid call after `INSUFFICIENT_POINTS`. Add points first, then use the zero-point balance or SDK/MCP preflight helper to check again. Preflight does not reserve points or a rate-limit slot, so callers must still handle a later 402.

## Points Cost

| Skill | Endpoint | Points/Call |
|-------|----------|-------------|
| Daily Model Reference Path | `POST /predictions/predict` | CN 10; US/HK/JP/KR/CRYPTO/UK/CA/DE/IN 20 |
| Algorithm Compare | `POST /predictions/compare` | Single prediction cost × number of algorithms |
| Quote | `GET /market-data/quote` | 5 |
| History | `GET /market-data/history` | 5 |
| Search | `GET /market-data/search` | 5 |
| Batch Quote | `POST /market-data/batch-quote` | 5 × number of symbols |
| Technical Analysis | `POST /technical/analyze` | 5 |
| Fear & Greed Index | `GET /sentiment/fear-greed` | 5 |
| Market Overview | `GET /sentiment/market-overview` | 5 |
| AI-Assisted Research Report | `POST /analysis/stock` | 58 |
| Multi-Factor Research Review | `POST /analysis/comprehensive` | 150 |
| Task Polling | `GET /analysis/task/{task_id}` | 0 (free) |
| Account Balance | `GET /account/balance` | 0 (free) |
| Usage Statistics | `GET /account/usage` | 0 (free) |
| API Info | `GET /info` | 0 (free) |
| Public Health | `GET /health` | 0 (free) |
| Auth Health | `GET /health/auth` | 0 (free) |
| Prediction Readiness | `GET /predictions/health` | 0 (free) |

---

## Skill 1: Daily Model Reference Path

Generate a daily model reference path and uncertainty range for research. The path is not actual future OHLCV or a trading instruction. Supports G-Prophet2026V1, G-Prophet2026V2 for CN/A-shares, LSTM, Transformer, and more.

### POST /predictions/predict

**Request Body (JSON):**

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| symbol | string | ✅ | - | Stock/crypto ticker (e.g. AAPL, 600519, BTCUSDT) |
| market | string | ✅ | - | Market code: `US`, `CN`, `HK`, `JP`, `KR`, `CRYPTO`, `UK`, `CA`, `DE`, `IN` |
| days | integer | No | 7 | Prediction days, range 1-30 |
| algorithm | string | No | auto | Algorithm: `auto`, `gprophet2026v1`, `gprophet2026v2` (CN only), `lstm`, `transformer`, `random_forest`, `ensemble` |

**Example Request:**

```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"}'
```

**Example Response:**

```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` provides one model reference price per market-local trading date and binds `uncertainty_lower` / `uncertainty_upper` to that same date. `currency` is the quote-currency code and `timezone` is the IANA market timezone used to interpret dates. `status` is `complete`, `partial`, or `unavailable`; unavailable or incomplete ranges use `null` bounds and are made explicit through `uncertainty.complete` and `warnings`.

`uncertainty.confidence_level` is a model-reported score. `confidence_level_semantics` is fixed to `model_reported_score_not_nominal_coverage`, explicitly stating that it is not nominal coverage. Do not interpret it as a calibrated “95% confidence interval.” These ranges are not action instructions. Path points are not actual future OHLCV; call `GET /market-data/history` for historical observed OHLCV. `POST /predictions/compare` currently returns algorithm summaries only, not a per-algorithm `model_reference_path`.

### POST /predictions/compare

Multi-algorithm comparison projection. Returns top-level `currency`, `timezone`, algorithm summaries, and a comparison result; per-algorithm daily reference paths are not currently returned. Points cost = single prediction cost × number of algorithms.

**Request Body (JSON):**

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| symbol | string | ✅ | - | Stock/crypto ticker |
| market | string | ✅ | - | Market code: `US`, `CN`, `HK`, `JP`, `KR`, `CRYPTO`, `UK`, `CA`, `DE`, `IN` |
| days | integer | No | 5 | Prediction days, range 1-30 |
| algorithms | string[] | No | CN: ["gprophet2026v2","gprophet2026v1","lstm","transformer","ensemble"]; other markets: ["gprophet2026v1","lstm","transformer","ensemble"] | Algorithm list, max 6. `gprophet2026v2` is CN only. |

**Example Request:**

```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"]}'
```

**Example Response:**

```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: Market Data

Get latest available quotes, historical observed OHLCV data, search for stocks/crypto, and batch quotes. Each call costs 5 points (batch = 5 × count).

### GET /market-data/quote

Get the latest available quote.

**Query Parameters:**

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| symbol | string | ✅ | Stock/crypto ticker |
| market | string | ✅ | Market code: `US`, `CN`, `HK`, `JP`, `KR`, `CRYPTO`, `UK`, `CA`, `DE`, `IN` |

**Example Request:**

```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"
```

**Example Response:**

```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` is the quote currency and `timezone` is the IANA market timezone used to interpret market dates and timestamps.

### GET /market-data/history

Get historical OHLCV candlestick data.

**Query Parameters:**

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| symbol | string | ✅ | - | Stock/crypto ticker |
| market | string | ✅ | - | Market code: `US`, `CN`, `HK`, `JP`, `KR`, `CRYPTO`, `UK`, `CA`, `DE`, `IN` |
| period | string | No | 3m | Time range: `1w`, `1m`, `3m`, `6m`, `1y`, `2y` |

**Example Request:**

```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"
```

**Example Response:**

```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
  }
}
```

Historical OHLCV contains observed market data; interpret each `date` in the response `timezone`.

### GET /market-data/search

Search for stocks/crypto by keyword.

**Query Parameters:**

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| keyword | string | ✅ | - | Search keyword |
| market | string | No | US | Market code: `US`, `CN`, `HK`, `JP`, `KR`, `CRYPTO`, `UK`, `CA`, `DE`, `IN` |
| limit | integer | No | 10 | Result count, range 1-50 |

**Example Request:**

```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"
```

The search response also returns top-level `currency` and `timezone` for interpreting the market and subsequent market-data responses.

### POST /market-data/batch-quote

Get the latest available quotes for multiple symbols in a single request. Max 20 symbols. Cost = 5 points × number of symbols.

**Request Body (JSON):**

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| symbols | string[] | ✅ | List of stock/crypto tickers (max 20) |
| market | string | ✅ | Market code: `US`, `CN`, `HK`, `JP`, `KR`, `CRYPTO`, `UK`, `CA`, `DE`, `IN` |

**Example Request:**

```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"}'
```

**Example Response:**

```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: Technical Analysis

Calculate technical indicators and summarize technical observations for a given stock. Each call costs 5 points.

### POST /technical/analyze

**Request Body (JSON):**

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| symbol | string | ✅ | - | Stock/crypto ticker |
| market | string | ✅ | - | Market code: `US`, `CN`, `HK`, `JP`, `KR`, `CRYPTO`, `UK`, `CA`, `DE`, `IN` |
| indicators | string[] | No | ["rsi","macd","bollinger","kdj"] | Indicators: `rsi`, `macd`, `bollinger`, `kdj`, `sma`, `ema` |

The raw HTTP endpoint defaults to four indicators. Python SDK 0.2.0 and the bundled MCP server explicitly request all six when `indicators` is omitted, at the same 5-point cost.

**Example Request:**

```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"]}'
```

**Example Response:**

```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: Market Sentiment

Get market sentiment data including Fear & Greed Index and market overview. Each call costs 5 points.

### GET /sentiment/fear-greed

Get the crypto market Fear & Greed Index.

**Query Parameters:**

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| days | integer | No | 1 | History days, 1=current only, range 1-365 |

**Example Request:**

```bash
curl "https://www.gprophet.com/api/external/v1/sentiment/fear-greed?days=1" \
  -H "X-API-Key: gp_sk_live_your_key"
```

**Example Response:**

```json
{
  "success": true,
  "data": {
    "value": 72,
    "classification": "greed",
    "previous_value": 68,
    "change": 4,
    "points_consumed": 5
  }
}
```

### GET /sentiment/market-overview

Get comprehensive market overview (breadth, hot sectors, major indices).

**Query Parameters:**

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| market | string | No | CN | Market code: `CN`, `US` |

**Example Request:**

```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-Assisted Research Report (Async)

Single-asset AI-assisted research report. Costs 58 points and supports all ten public markets.

> ⚠️ **Async Mode**: Analysis typically takes 15-60 seconds, so this endpoint uses async mode.
> 1. `POST /analysis/stock` → Returns `task_id` immediately
> 2. `GET /analysis/task/{task_id}` → Poll for status; get results when `status=completed`
>
> Recommended polling interval: 5 seconds. Max wait: 5 minutes.

### POST /analysis/stock

Submit a stock analysis task. Returns task ID immediately.

**Request Body (JSON):**

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| symbol | string | ✅ | - | Stock/crypto ticker |
| market | string | ✅ | - | Market code: `US`, `CN`, `HK`, `JP`, `KR`, `CRYPTO`, `UK`, `CA`, `DE`, `IN` |
| locale | string | No | zh-CN | Report language: `zh-CN`, `en-US` |
| callback_url | string | No | - | Publicly reachable HTTPS webhook URL; localhost, private-network addresses, and internal hostnames are forbidden |

**Example Request:**

```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"}'
```

**Example Response (immediate):**

```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: Multi-Factor Research Review (Async)

Multi-agent research review across technical, fundamental, capital-flow, sentiment, and macro dimensions. Costs 150 points and supports all ten public markets.

> ⚠️ **Async Mode**: A multi-factor research review typically takes 30-120 seconds, so this endpoint uses async mode.
> 1. `POST /analysis/comprehensive` → Returns `task_id` immediately
> 2. `GET /analysis/task/{task_id}` → Poll for status; get results when `status=completed`
>
> Recommended polling interval: 5 seconds. Max wait: 5 minutes.

### POST /analysis/comprehensive

Submit a multi-factor research review task. Returns a task ID immediately.

**Request Body (JSON):**

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| symbol | string | ✅ | - | Stock/crypto ticker |
| market | string | ✅ | - | Market code: `US`, `CN`, `HK`, `JP`, `KR`, `CRYPTO`, `UK`, `CA`, `DE`, `IN` |
| locale | string | No | zh-CN | Report language: `zh-CN`, `en-US` |
| callback_url | string | No | - | Publicly reachable HTTPS webhook URL; localhost, private-network addresses, and internal hostnames are forbidden |

**Example Request:**

```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": "en-US"}'
```

**Example Response (immediate):**

```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 Callback

Both `/analysis/stock` and `/analysis/comprehensive` accept an optional `callback_url` parameter. It must use HTTPS and resolve to a publicly reachable destination. Localhost, loopback, link-local, private-network addresses, internal hostnames, and redirects to any such destination are forbidden. When provided, the API will POST the task result to that URL upon completion or failure:

**Callback Payload (success):**

```json
{
  "task_id": "task_abc123def456",
  "status": "completed",
  "result": {}
}
```

**Callback Payload (failure):**

```json
{
  "task_id": "task_abc123def456",
  "status": "failed",
  "error": "Analysis service timeout"
}
```

### GET /analysis/task/{task_id}

Poll analysis task status and results.

**Path Parameters:**

| Parameter | Type | Description |
|-----------|------|-------------|
| task_id | string | Task ID returned by analysis endpoints |

**Example Request:**

```bash
curl "https://www.gprophet.com/api/external/v1/analysis/task/task_abc123def456" \
  -H "X-API-Key: gp_sk_live_your_key"
```

**Status Flow:** `pending` → `running` (progress 0-100) → `completed` / `failed`

**Example Response (in progress):**

```json
{
  "success": true,
  "data": {
    "task_id": "task_abc123def456",
    "status": "running",
    "progress": 45,
    "message": "Analyzing fundamental data...",
    "result": null,
    "error": null
  }
}
```

**Example Response (completed):**

```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 golden cross", "Above 20-day MA"],
            "summary": "Technical outlook is bullish..."
          },
          "fundamental": {
            "rating": "neutral",
            "confidence": 0.65,
            "key_points": ["Reasonable PE", "Revenue growth slowing"],
            "summary": "Fundamentals are neutral..."
          },
          "capital_flow": {
            "rating": "bullish",
            "confidence": 0.70,
            "key_points": ["Net institutional inflow"],
            "summary": "Capital flow is positive..."
          },
          "sentiment": {
            "rating": "neutral",
            "confidence": 0.60,
            "key_points": ["Stable market sentiment"],
            "summary": "Sentiment is neutral..."
          },
          "macro": {
            "rating": "cautious",
            "confidence": 0.55,
            "key_points": ["Rate hike expectations", "Geopolitical risks"],
            "summary": "Macro environment is cautious..."
          }
        },
        "research_observation": "Short-term upward model bias; monitor volatility and macro risk",
        "risk_level": "medium"
      }
    },
    "error": null
  }
}
```

**Example Response (failed):**

```json
{
  "success": true,
  "data": {
    "task_id": "task_abc123def456",
    "status": "failed",
    "progress": 100,
    "message": "Analysis service timeout",
    "result": null,
    "error": "Analysis service timeout"
  }
}
```

---

## Account Endpoints

### GET /account/balance

Check current API Key's points balance and quota usage. Free, no points consumed.

**Example Request:**

```bash
curl "https://www.gprophet.com/api/external/v1/account/balance" \
  -H "X-API-Key: gp_sk_live_your_key"
```

**Example Response:**

```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

Get call history statistics for the current API Key. Free, no points consumed.

**Query Parameters:**

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| days | integer | No | 7 | History days, range 1-90 |

**Example Request:**

```bash
curl "https://www.gprophet.com/api/external/v1/account/usage?days=7" \
  -H "X-API-Key: gp_sk_live_your_key"
```

**Example Response:**

```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

Get public API metadata: supported markets, market details, currencies, IANA timezones, algorithms, pricing, and endpoint support. Free, no API key required, and no points consumed.

**Example Request:**

```bash
curl "https://www.gprophet.com/api/external/v1/info"
```

**Key response fields:**

```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 integrations should read `supported_markets` and `market_details` from `GET /info` instead of hard-coding an old market list.

---

## Health Checks

All three checks consume zero points and do not run a model:

| Endpoint | Authentication | Purpose |
|----------|----------------|---------|
| `GET /health` | No API key | Confirms that the request reached the G-Prophet origin |
| `GET /health/auth` | `X-API-Key` | Validates the key and owner; reports scopes, quota counters, and points |
| `GET /predictions/health?market=US` | `X-API-Key` with predictions scope | Checks the key, scope, market, and points needed for one model run |

These routes do not reserve points or a rate-limit slot. Reported quota counters are informational; callers must still handle a later 402, 403, or 429.

---

## Error Codes

| Code | HTTP Status | Description |
|------|-------------|-------------|
| MISSING_API_KEY | 401 | Missing X-API-Key header |
| INVALID_KEY_FORMAT | 401 | Invalid API Key format (must start with gp_sk_) |
| INVALID_API_KEY | 401 | Invalid API Key |
| API_KEY_DISABLED | 403 | API Key has been disabled |
| API_KEY_EXPIRED | 403 | API Key has expired |
| INSUFFICIENT_SCOPE | 403 | API Key lacks permission for this Skill |
| INSUFFICIENT_POINTS | 402 | Insufficient points; `retryable: false`, add points before another paid call |
| POINTS_DEDUCTION_FAILED | 500 | Failed to deduct points |
| OWNER_NOT_FOUND | 403 | API Key owner account not found |
| RATE_LIMITED | 429 | Request frequency exceeded per-minute limit |
| QUOTA_EXCEEDED | 429 | Daily or monthly call quota exhausted |
| INVALID_MARKET | 422 | Unsupported market code |
| UNSUPPORTED_MARKET | 422 | Market not supported for this endpoint |
| UNSUPPORTED_ALGORITHM_MARKET | 422 | Selected algorithm is unavailable for the market; G-Prophet2026V2 is CN/A-share only |
| SYMBOL_NOT_FOUND | 422 | Stock/crypto ticker not found |
| NO_DATA | 422 | Unable to retrieve data |
| VALIDATION_ERROR | 422 | Request validation failed |
| TOO_MANY_ALGORITHMS | 400 | Too many algorithms (max 6) |
| PREDICTION_FAILED | 500 | Prediction service error |
| TASK_NOT_FOUND | 404 | Async task not found or expired |
| FORBIDDEN | 403 | Access denied (e.g. querying another user's task) |
| DATA_UNAVAILABLE | 503 | Data source temporarily unavailable |
| DATA_SOURCE_UNAVAILABLE | 503 | Historical market data is temporarily unavailable |
| INTERNAL_ERROR | 500 | Internal service error |

Do not infer that a missing `retryable` field means a request is safe to repeat. In particular, a paid request that ends with a read timeout, connection reset after sending, or invalid/non-JSON gateway response may already have consumed points. Check usage, balance, or task state before deciding whether to issue another paid call.

---

## MCP Tools Definitions

MCP (Model Context Protocol) tool definitions for use with Claude, Kiro, and other MCP-compatible agents:

> **IMPORTANT FOR AI AGENTS**: These tools are designed to be called through the MCP protocol, NOT by constructing raw HTTP requests. If you are an AI agent without MCP access, use the Python SDK (`pip install gprophet`) or make HTTP requests to the base URL `https://www.gprophet.com/api/external/v1` with the `X-API-Key` header. Do NOT fabricate or guess endpoint URLs — always use the exact paths documented above (e.g., `POST /predictions/predict`, not `/predict` or `/api/predict`).

### gprophet_predict

```json
{
  "name": "gprophet_predict",
  "description": "Generate a daily model reference path for US, CN, HK, JP, KR, CRYPTO, UK, CA, DE, or IN. Returns currency, IANA timezone, model_reference_path, and date-aligned uncertainty bounds. uncertainty.confidence_level is model-reported, not nominal coverage; never read it as a calibrated confidence interval. Path points are not actual future OHLCV. G-Prophet2026V2 is CN-only. Cost is published by gprophet_info (currently CN 10 points, other markets 20); use the free gprophet_preflight tool when affordability is uncertain.",
  "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": "Compare model projection summaries across algorithms. Cost equals the market's single prediction price multiplied by the number of algorithms. Use gprophet_preflight with operation=compare and count=<algorithm count> first when affordability is uncertain.",
  "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": "Get the latest available stock/crypto quote with quote currency and IANA market timezone. Costs 5 points. Use free gprophet_preflight(operation=quote) if balance is uncertain; never retry a 402 until points change.",
  "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": "Get quotes for multiple symbols at once (max 20), with quote currency and IANA market timezone. Costs 5 points per symbol; preflight with operation=batch_quote and count=<symbol count>.",
  "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": "Get observed historical OHLCV data with quote currency and IANA market timezone. Costs 5 points; preflight explicitly when balance is uncertain.",
  "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": "Search for stocks/crypto by keyword; the response includes market currency and timezone. Costs 5 points.",
  "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": "Calculate permission-allowed technical indicators (RSI, MACD, Bollinger, KDJ, SMA, EMA), with market currency and timezone, and summarize research observations. Costs 5 points. All six indicators are requested by default.",
  "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": "Get crypto market Fear & Greed Index. Costs 5 points.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "days": { "type": "integer", "minimum": 1, "maximum": 365, "default": 1 }
    }
  }
}
```

### gprophet_market_overview

```json
{
  "name": "gprophet_market_overview",
  "description": "Get market overview research context: breadth, hot concepts, major indices. Costs 5 points.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "market": { "type": "string", "enum": ["CN", "US"], "default": "CN" }
    }
  }
}
```

### gprophet_analyze_stock

```json
{
  "name": "gprophet_analyze_stock",
  "description": "Run an AI-assisted research report (58 points, async) for any public market. Returns task_id for polling via gprophet_task_status. Use the free gprophet_preflight tool first when affordability is uncertain.",
  "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": "Run a multi-agent, multi-factor research review (150 points, async) for any public market. Returns task_id for polling via gprophet_task_status. Use the free gprophet_preflight tool first when affordability is uncertain.",
  "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": "Check the status of an async analysis task. Free; poll about every 5 seconds.",
  "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": "Check public API origin reachability. Free and does not validate account readiness.",
  "inputSchema": { "type": "object", "properties": {} }
}
```

### gprophet_auth_health

```json
{
  "name": "gprophet_auth_health",
  "description": "Validate the API key/account and report scopes, quota counters, and points for free.",
  "inputSchema": { "type": "object", "properties": {} }
}
```

### gprophet_prediction_health

```json
{
  "name": "gprophet_prediction_health",
  "description": "Check prediction scope, market, and one-run point affordability without spending points.",
  "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": "Check current points balance and API quota. Free. Prefer gprophet_preflight when planning a specific paid call.",
  "inputSchema": { "type": "object", "properties": {} }
}
```

### gprophet_usage

```json
{
  "name": "gprophet_usage",
  "description": "Get API usage statistics for the current key. Free.",
  "inputSchema": {
    "type": "object",
    "properties": {
      "days": { "type": "integer", "minimum": 1, "maximum": 90, "default": 7 }
    }
  }
}
```

### gprophet_info

```json
{
  "name": "gprophet_info",
  "description": "Get API metadata: supported markets, currencies, IANA timezones, algorithms, and pricing.",
  "inputSchema": { "type": "object", "properties": {} }
}
```

### gprophet_preflight

```json
{
  "name": "gprophet_preflight",
  "description": "Free planning check: read live pricing and account balance, then evaluate known point, scope, and quota gates. It does not reserve points or a rate-limit slot; a later paid call can still fail. For compare and batch_quote, count must equal the actual algorithm or symbol 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"]
  }
}
```

After input passes MCP schema validation, API and tool-execution failures are returned as structured errors and marked with MCP `isError`. Schema-validation failures occur before the handler runs and are protocol-native MCP errors; they are not guaranteed to contain the tool's structured envelope or `structuredContent`. Follow `error.details.retryable`; do not automatically repeat paid calls after 402, quota exhaustion, read timeout, or an invalid/non-JSON gateway response. A paid call whose response was lost may already have consumed points.

---

## Integration Guide

### Typical Model Reference Flow

```
1. If account state is uncertain, call gprophet_preflight(operation="predict", market=...)
2. Search first when the symbol is uncertain; preserve the returned canonical symbol, name, and market
3. Call gprophet_predict, then read currency, timezone, model_reference_path.points, and date-aligned uncertainty bounds
4. Optionally call gprophet_history and gprophet_technical for observed data and indicator context
5. Present the result as a research observation, not a buy/sell/hold instruction
```

### Typical Research Report Flow

```
1. Call gprophet_analyze_stock to submit analysis task → get task_id
2. Poll gprophet_task_status every 5 seconds
3. When status = "completed", read the analysis report from result
4. When status = "failed", read the failure reason from error
```

### Typical Multi-Factor Research Review Flow

```
1. Call gprophet_analyze_comprehensive to submit analysis task → get task_id
2. Poll gprophet_task_status every 5 seconds
3. When status = "completed", read the full report from result.analysis
4. When status = "failed", read the failure reason from error
```

### Webhook Integration Flow

```
1. Call POST /analysis/stock or /analysis/comprehensive with a permitted, publicly reachable HTTPS callback_url
2. Continue processing other tasks (no need to poll)
3. Receive POST to your callback_url when task completes or fails
4. Verify task_id and process the result
```

### Agent Integration Tips

- **Search before model calls**: If unsure about a ticker, use `gprophet_search` and preserve its canonical `symbol`, `name`, and `market`
- **Combine context**: Review the model reference path, observed OHLCV, uncertainty, technical indicators, and market context together
- **Account planning**: Use `gprophet_preflight` before a paid operation when account state is uncertain; supply exact `count` for compare or batch quote
- **Batch operations**: Use `gprophet_batch_quote` instead of multiple single quotes to save API calls
- **Error handling**: Follow `error.details.retryable`; never auto-retry a 402, quota exhaustion, or ambiguous paid-call timeout
- **Webhooks**: Use only publicly reachable HTTPS callback URLs; never use localhost, private-network addresses, or internal hostnames

### Python SDK 0.2.0

The core SDK supports Python 3.8+. The MCP extra requires 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")  # Zero points; reserves nothing.

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())  # Account state may change after preflight.
```

SDK/MCP technical calls request all six supported indicators when `indicators` is omitted. Public HTTP `GET /health` and `GET /info` need no key; account checks and all paid tools do. A preflight evaluates known point, scope, and quota gates using live pricing, but it does not reserve points or a rate-limit slot. With Python SDK `wait=True`, a post-creation polling failure includes the existing `task_id`; continue with `client.task_status(task_id)` and never resubmit the paid analysis automatically.

---

## Supported Market Codes

| Code | Market | Ticker Format | Example Tickers |
|------|--------|---------------|-----------------|
| US | US Stocks | Alphabetic ticker symbol | AAPL, TSLA, GOOGL, MSFT |
| CN | China A-shares | 6-digit number. 6xxxxx=Shanghai, 0/3xxxxx=Shenzhen | 600519, 000001, 300750 |
| HK | Hong Kong Stocks | Numeric code accepts bare digits, 4-digit zero-padded code, or `.HK` suffix; the service normalizes common forms | 700, 0700, 700.HK, 9988 |
| JP | Japan Stocks | 4-5 character TSE symbol; accepts a bare symbol or `.T` suffix | 7203, 7203.T, 130A.T |
| KR | Korea Stocks | 6-digit KRX symbol; accepts a bare symbol, `.KS`, or `.KQ` suffix | 005930, 005930.KS, 035420.KQ |
| CRYPTO | Cryptocurrency | Trading pair (ending in USDT) | BTCUSDT, ETHUSDT, SOLUSDT |
| UK | UK Stocks | The market code is `UK`; LSE-style symbols are accepted with normalization | HSBA.LON, TSCO.LON, BP.LON, SHEL.LON, AZN.LON |
| CA | Canada Stocks | TSX-style symbols accepted with normalization | SHOP.TRT, CNR.TRT, RY.TRT, TD.TRT |
| DE | Germany Stocks | XETRA/Germany suffix variants accepted with normalization | SAP.DEX, SIE.DEX, ALV.DEX, MBG.DEX |
| IN | India Stocks | NSE/BSE suffix variants accepted with normalization | RELIANCE.NS, TCS.NS, INFY.NS, HDFCBANK.NS |

## Future Market Extension Rule

- The call pattern stays the same: pass `market=<market code>`.
- AI/SDK/MCP clients should call `GET /info` and read `supported_markets` plus `market_details` instead of hard-coding an old market list.
- Once a new market appears in `/info.supported_markets`, call the same endpoint paths, for example `GET /market-data/quote?symbol=...&market=XX`.
- If an endpoint does not support a market, the API returns `UNSUPPORTED_MARKET` or `INVALID_MARKET`; do not change the URL path, adjust `market` or choose an endpoint that supports that market.
- Suggested automation flow: call `GET /market-data/search` first, then call `predict` with the canonical `symbol` returned by search. If search returns no result, do not call `predict`, to avoid unnecessary point usage.
- Hong Kong bare numeric symbols are accepted, for example `symbol=700&market=HK`; the service treats it as `0700`. Clients may also send `0700` or `700.HK`.
- Japan accepts forms such as `7203` and `7203.T`. Korea uses 6-digit symbols and accepts `.KS` / `.KQ` suffixes such as `005930.KS` and `035420.KQ`.
- `UK` is the official market code for UK stocks. Do not use `GB` or `LSE` as the market parameter; exchange details belong in the symbol suffix, such as `HSBA.LON`.
- International markets may have slower upstream data sources, so use a timeout of at least 120 seconds. Do not automatically repeat a paid call after a read timeout: the server may already have consumed points. Check usage, balance, or task state first.

> ⚠️ **A-share Ticker Notes**:
> - A-share tickers are **6-digit numbers**; different prefixes indicate different exchanges/boards
> - `6xxxxx` = Shanghai Stock Exchange (Main Board / STAR Market)
> - `0xxxxx` = Shenzhen Stock Exchange (Main Board / SME Board)
> - `3xxxxx` = Shenzhen Stock Exchange (ChiNext / Growth Enterprise Market)
> - Make sure to pass the correct 6-digit code, e.g. `600986` (Zhewenhulan) and `000001` (Ping An Bank) are different stocks

## Supported Prediction Algorithms

| Algorithm | Description |
|-----------|-------------|
| auto | Automatically select the best algorithm |
| gprophet2026v1 | G-Prophet2026V1 proprietary model |
| gprophet2026v2 | G-Prophet2026V2 A-share model, CN only |
| lstm | Long Short-Term Memory network |
| transformer | Transformer model |
| random_forest | Random Forest |
| ensemble | Ensemble learning (multi-algorithm fusion) |