data912-market-data

查询阿根廷和美国工具的 Data912 市场数据端点。 当用户询问 MEP/CCL 报价、实时阿根廷市场面板时使用 （股票、期权、雪松、票据、公司债务、债券）、美国面板（美国存托凭证、股票）、 OHLC 历史系列（按股票代码、美国期权链或波动性/风险指标）。 当用户提到“Data912”、“mep”、“ccl”、“cedears”、“option chain”时也使用 “历史柱”、“OHLC”、“隐含波动率”、“历史波动率”或 “波动率百分位”并期望 API 支持的市场快照。

# Data912 Market Data

Query Data912's public market API for Argentina and USA market data snapshots, historical bars, and EOD derivatives analytics.

## API Overview

- **Base URL**: `https://data912.com`
- **Auth**: None required (public API)
- **Format**: JSON responses
- **Source note**: Data912 describes this API as educational/hobby data and explicitly not real-time.
- **Caching note**: Server metadata indicates roughly 2-hour Cloudflare caching.

## Endpoint Groups

### 1. Live Market Panels

- `/live/mep` (USD MEP)
- `/live/ccl` (USD CCL)
- `/live/arg_stocks`
- `/live/arg_options`
- `/live/arg_cedears`
- `/live/arg_notes`
- `/live/arg_corp`
- `/live/arg_bonds`
- `/live/usa_adrs`
- `/live/usa_stocks`

Example:

```bash
curl -s "https://data912.com/live/arg_stocks" | jq '.[0:5]'
```

### 2. Historical OHLC

- `/historical/stocks/{ticker}`
- `/historical/cedears/{ticker}`
- `/historical/bonds/{ticker}`

Example:

```bash
curl -s "https://data912.com/historical/stocks/GGAL" | jq '.[0:10]'
```

### 3. EOD Derivatives Analytics

- `/eod/volatilities/{ticker}`
- `/eod/option_chain/{ticker}`

Examples:

```bash
curl -s "https://data912.com/eod/volatilities/AAPL" | jq '.'
curl -s "https://data912.com/eod/option_chain/AAPL" | jq '.[0:10]'
```

### Out of Scope for This Skill

- Do not use `/contact` in this skill. Keep this skill focused on market data retrieval and interpretation.

## Key Fields

### Panel Fields (`/live/*`)

- `symbol`: instrument ticker/symbol
- `px_bid`, `q_bid`: bid price and bid size
- `px_ask`, `q_ask`: ask price and ask size
- `c`: last/close-like traded value
- `pct_change`: percentage variation
- `v`: volume
- `q_op`: operations count (when provided)

### Historical Fields (`/historical/*/{ticker}`)

- `date`: date string
- `o`, `h`, `l`, `c`: OHLC values
- `v`: volume
- `dr`: daily return
- `sa`: additional numeric metric provided by source

### Volatility Metrics (`/eod/volatilities/{ticker}`)

- IV term structure: `iv_s_term`, `iv_m_term`, `iv_l_term`
- IV percentiles: `iv_*_percentile`
- HV term structure: `hv_s_term`, `hv_m_term`, `hv_l_term`
- HV percentiles: `hv_*_percentile`
- Relative-value ratios: `iv_hv_*_ratio`, `iv_fair_iv_ratio`
- Fair value reference: `fair_iv`, `fair_iv_percentile`

### Option Chain Fields (`/eod/option_chain/{ticker}`)

- Contract context: `opex`, `s_symbol`, `type`, `k`
- Market data: `bid`, `ask`, `c`, `oi`
- Greeks: `delta`, `gamma`, `theta`, `vega`, `rho`
- Valuation/probabilities: `fair_value`, `fair_iv`, `itm_prob`, `intrinsic`, `otm`
- Horizon context: `r_days`, `r_tdays`, `hv_2m`, `hv_1yr`

## Workflow

1. **Identify intent** and select endpoint group:
   - FX/panel snapshot -> `/live/*`
   - Time series/evolution -> `/historical/*/{ticker}`
   - Options/risk analytics -> `/eod/*/{ticker}`
2. **Validate required input**:
   - For historical/EOD endpoints, require a ticker symbol.
   - If ticker is missing, ask for it before querying.
3. **Fetch data with `curl -s`** and parse with `jq`.
4. **Handle empty arrays**:
   - If response is `[]`, report: "No data currently available for this endpoint/ticker."
5. **Present an actionable summary**:
   - Start with a short snapshot.
   - Then include relevant detail fields requested by the user.
6. **Keep context clear**:
   - Remind users this is educational/non-real-time data.
   - Avoid turning output into trading advice.

## Error Handling

- **429 Too Many Requests**:
  - Most market endpoints publish `120 req/min`.
  - Back off and retry after a short delay; avoid burst loops.
- **422 Validation Error**:
  - Usually invalid/missing path input such as ticker formatting.
  - Re-check symbol and endpoint before retrying.
- **Network/timeout failures**:
  - Retry a small number of times (for example, 2 retries with delay).
  - If still failing, return a clear failure message and the endpoint attempted.

## Presenting Results

When returning results to the user:

- Lead with a concise snapshot (what moved, where, and magnitude).
- For panel requests, compare bid/ask/last and `% change`.
- For historical requests, summarize trend windows and notable jumps.
- For vol/options requests, highlight percentiles and IV/HV relationships.
- Explicitly mention the data is educational/non-real-time.
- Do not provide financial recommendations.

## OpenAPI Spec

For the full schema and endpoint definitions, see [references/openapi-spec.json](references/openapi-spec.json).

---

## 中文说明

# Data912 市场数据

查询 Data912 的公开市场 API，获取阿根廷和美国的市场数据快照、历史柱以及 EOD 衍生品分析。

## API 概览

- **Base URL**：`https://data912.com`
- **认证**：无需（公开 API）
- **格式**：JSON 响应
- **来源说明**：Data912 将此 API 描述为教育/业余数据，并明确表示其非实时。
- **缓存说明**：服务器元数据显示大约有 2 小时的 Cloudflare 缓存。

## 端点分组

### 1. 实时市场面板

- `/live/mep` (USD MEP)
- `/live/ccl` (USD CCL)
- `/live/arg_stocks`
- `/live/arg_options`
- `/live/arg_cedears`
- `/live/arg_notes`
- `/live/arg_corp`
- `/live/arg_bonds`
- `/live/usa_adrs`
- `/live/usa_stocks`

示例：

```bash
curl -s "https://data912.com/live/arg_stocks" | jq '.[0:5]'
```

### 2. 历史 OHLC

- `/historical/stocks/{ticker}`
- `/historical/cedears/{ticker}`
- `/historical/bonds/{ticker}`

示例：

```bash
curl -s "https://data912.com/historical/stocks/GGAL" | jq '.[0:10]'
```

### 3. EOD 衍生品分析

- `/eod/volatilities/{ticker}`
- `/eod/option_chain/{ticker}`

示例：

```bash
curl -s "https://data912.com/eod/volatilities/AAPL" | jq '.'
curl -s "https://data912.com/eod/option_chain/AAPL" | jq '.[0:10]'
```

### 本技能范围之外

- 本技能不要使用 `/contact`。保持本技能专注于市场数据的获取与解读。

## 关键字段

### 面板字段（`/live/*`）

- `symbol`：工具代码/符号
- `px_bid`、`q_bid`：买价与买量
- `px_ask`、`q_ask`：卖价与卖量
- `c`：最新/类收盘成交值
- `pct_change`：百分比变动
- `v`：成交量
- `q_op`：操作次数（如有提供）

### 历史字段（`/historical/*/{ticker}`）

- `date`：日期字符串
- `o`、`h`、`l`、`c`：OHLC 值
- `v`：成交量
- `dr`：日收益率
- `sa`：来源提供的额外数值指标

### 波动率指标（`/eod/volatilities/{ticker}`）

- IV 期限结构：`iv_s_term`、`iv_m_term`、`iv_l_term`
- IV 百分位：`iv_*_percentile`
- HV 期限结构：`hv_s_term`、`hv_m_term`、`hv_l_term`
- HV 百分位：`hv_*_percentile`
- 相对价值比率：`iv_hv_*_ratio`、`iv_fair_iv_ratio`
- 公允价值参考：`fair_iv`、`fair_iv_percentile`

### 期权链字段（`/eod/option_chain/{ticker}`）

- 合约上下文：`opex`、`s_symbol`、`type`、`k`
- 市场数据：`bid`、`ask`、`c`、`oi`
- 希腊字母：`delta`、`gamma`、`theta`、`vega`、`rho`
- 估值/概率：`fair_value`、`fair_iv`、`itm_prob`、`intrinsic`、`otm`
- 期限上下文：`r_days`、`r_tdays`、`hv_2m`、`hv_1yr`

## 工作流

1. **识别意图** 并选择端点分组：
   - 外汇/面板快照 -> `/live/*`
   - 时间序列/演变 -> `/historical/*/{ticker}`
   - 期权/风险分析 -> `/eod/*/{ticker}`
2. **校验必需输入**：
   - 对于历史/EOD 端点，需要一个股票代码。
   - 如果缺少股票代码，在查询前先询问。
3. **用 `curl -s` 获取数据** 并用 `jq` 解析。
4. **处理空数组**：
   - 如果响应为 `[]`，报告："No data currently available for this endpoint/ticker."
5. **呈现可操作的摘要**：
   - 以一个简短快照开始。
   - 然后包含用户请求的相关明细字段。
6. **保持上下文清晰**：
   - 提醒用户这是教育/非实时数据。
   - 避免将输出变成交易建议。

## 错误处理

- **429 Too Many Requests**：
  - 大多数市场端点公布的限制为 `120 req/min`。
  - 退避后短暂延迟再重试；避免突发循环。
- **422 Validation Error**：
  - 通常是无效/缺失的路径输入，例如股票代码格式问题。
  - 重新核对符号与端点后再重试。
- **网络/超时失败**：
  - 重试少量次数（例如 2 次，带延迟）。
  - 如果仍然失败，返回清晰的失败信息以及尝试过的端点。

## 呈现结果

向用户返回结果时：

- 以简洁快照开头（什么变动了、在哪里、幅度多大）。
- 对于面板请求，比较买价/卖价/最新价以及 `% change`。
- 对于历史请求，总结趋势窗口和显著跳变。
- 对于波动率/期权请求，突出百分位以及 IV/HV 关系。
- 明确提及数据为教育/非实时性质。
- 不提供财务建议。

## OpenAPI 规范

完整的 schema 与端点定义请参见 [references/openapi-spec.json](references/openapi-spec.json)。