合作方数据 API

瓯衍公开数据站的**结构化接口**（P1 · 白名单制）。用 X-Api-Key 鉴权， 只提供统计结果（基差率、分位、ATM IV 等），不含逐笔明细、策略持仓或方向判断。

契约版本 1.0 JSON 按 key 限流 自然月配额

← 回到瓯衍数据站  ·  数据口径（字段含义以此为准）  ·  方法论台账（已否决方向）

如何获得密钥

目前**不开放自助注册**。请通过 联系我们 说明用途、调用频率与所需字段，我们按白名单签发一把密钥，并约定配额与责任边界。

密钥只在签发时显示一次。服务端只保存 SHA-256 哈希，无法找回；丢失只能吊销后重发。 请通过安全渠道保存，不要写进前端代码或公开仓库。

鉴权

所有数据端点都需要在请求头带上密钥：

X-Api-Key: fa_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

密钥格式：fa_live_ + 32 位十六进制。 只认 X-Api-Key 这一个头（Authorization: Bearer 留给登录用户 JWT，两者不混用）。

端点

1. 探活（无需密钥）

GET /api/v1/open/ping
{
  "service": "oyan-open-api",
  "schemaVersion": "1.0",
  "status": "ok",
  "serverTime": "2026-11-15T08:12:31.1234567+00:00"
}

2. 基本面快照 fundamental:read

GET /api/v1/open/fundamental/basis?product=RB&window=250
参数说明
product品种代码（如 RB），省略=全部
window分位窗口（交易日），5–500，默认 250
{
  "meta": {
    "generatedAt": "2026-11-15T08:12:31.12+00:00",
    "dataDate": "2026-11-13",
    "schemaVersion": "1.0",
    "serviceReady": true,
    "key": { "name": "XX 研究所-日频拉取", "scopes": ["fundamental:read"] },
    "quota": { "perMinute": 60, "monthly": 100000, "monthUsed": "128" }
  },
  "rows": [
    {
      "product": "RB",
      "tradeDate": "2026-11-13",
      "basisRatePct": 4.32,
      "basisRatePctile": 100,
      "basisRateChg20Pp": 1.12,
      "inventory": 123456,
      "inventoryChg": -1173,
      "inventoryPctile": 4,
      "profit": null,
      "profitRatePct": null,
      "profitPctile": null,
      "virtualReal": 1.83,
      "virtualRealPctile": 62,
      "basisQuality": "ok"
    }
  ],
  "disclaimer": "数据为交易所公开行情与公告的统计整理，仅供研究参考，不构成投资建议或收益承诺。"
}
缺失即 null，不补零：分位样本不足、某品种无库存/利润数据时对应字段为 null。 请按 null 处理，不要当作 0——那会把"没数据"读成"数值为零"。

3. 期权隐波 options:read

GET /api/v1/open/options/iv?product=AU
{
  "meta": { "dataDate": "2026-11-13", "schemaVersion": "1.0", "...": "同上" },
  "rows": [
    {
      "product": "AU",
      "tradeDate": "2026-11-13",
      "nearAtmIv": 16.84,
      "nextAtmIv": 17.51,
      "termSlopePp": 0.67,
      "fwdIv": null,
      "inverted": false,
      "nearIvPctile": 93,
      "source": "term"
    }
  ],
  "disclaimer": "…"
}
字段口径
termSlopePp次月 ATM IV − 近月 ATM IV（百分点）。正=顺挂；任一侧缺失为 null
nearIvPctile近月 IV 在自身历史中的分位（0–100），与公开站同口径
sourceterm=期限结构因子（日更，字段全）/ atm=ATM 因子表（周更，仅 ATM IV）

配额与限流

维度行为
每分钟固定 60 秒窗口，按密钥计。超限返回 429 + Retry-After（秒）
自然月按调用次数累计。超限返回 429，Retry-After 指向下月 1 日 0 点（UTC）

每个成功响应都会回显当前配额，便于客户端自适应：

X-Api-Quota-Limit: 60
X-Api-Quota-Remaining: 58
X-Api-Month-Used: 128
X-Api-Month-Quota: 100000

错误码

HTTPerror含义 / 处理
401missing_api_key没带 X-Api-Key
401invalid_api_key密钥不存在或已吊销（不区分，防探测）
403insufficient_scope密钥有效但没买这个数据范围
429minute_quota_exceeded按 Retry-After 退避后重试
429monthly_quota_exceeded本月额度用尽，需等下月或申请提额
503service_unavailable服务端密钥库不可达（**不是密钥问题**），请稍后重试并通知我们
{ "error": "insufficient_scope", "message": "该密钥未获得范围 options:read。", "status": 403 }

使用约定