快速开始

基础 URL 与约定

基础 URL	https://calc.dev.emrgex.com
前缀	所有端点均位于 /v1 之下
利率与收益率	小数形式 —— 0.06 表示 6%
价格	以面值 100 为基准
日期	ISO 格式 YYYY-MM-DD
内容类型	application/json

你的第一个请求

为一只已存储的工具定价 —— 通过 instrument_id 引用它，并给出收益率：

curl -s https://calc.dev.emrgex.com/v1/quotes \
  -H 'content-type: application/json' \
  -d '{
    "quotes": [
      { "instrument_id": "MH12034", "input_kind": "yield", "input_value": 0.10,
        "settlement_date": "2026-06-09", "options": { "round": 6 } }
    ]
  }'

响应是一个批量信封（batch envelope） —— 每条报价对应一个条目，各自带有自己的 status：

{
  "data": [
    {
      "index": 0,
      "id": "MH12034",
      "status": "ok",
      "data": {
        "instrument_id": "MH12034",
        "convention": "NOMINAL · ACT/ACT.DRMH",
        "calculation_code": "ACT/ACT.DRMH|NOMINAL",
        "metrics": {
          "yield": 0.1,
          "dirty_price": 112.547645,
          "clean_price": 107.853124,
          "accrued_interest": 4.694521,
          "modified_duration": 5.12,
          "convexity": 33.7,
          "dv01": 0.0576
        }
      }
    }
  ]
}

用价格而非收益率定价

将 input_kind 设为 clean_price 或 dirty_price，emrgex 会为你反解出收益率：

{ "instrument_id": "MH12034", "input_kind": "clean_price", "input_value": 107.85,
  "settlement_date": "2026-06-09", "options": { "round": 6 } }

自定义债券（临时定义，ad-hoc）

将工具内联放入 instruments 中，然后在 quotes 中通过其 id 引用它：

curl -s https://calc.dev.emrgex.com/v1/quotes \
  -H 'content-type: application/json' \
  -d '{
    "instruments": [
      { "id": "B1", "rate_type": "NOMINAL", "day_count": "ACT/ACT.ICMA",
        "coupon_type": "FIXED", "frequency": 2,
        "start": "2020-01-15", "maturity": "2030-01-15",
        "coupon_rate": 0.06, "face_value": 100 }
    ],
    "quotes": [
      { "instrument_id": "B1", "input_kind": "clean_price", "input_value": 95.5,
        "settlement_date": "2024-06-18", "options": { "round": 6 } }
    ]
  }'

加上交易规模

提供 amount 即可在每 100 面值价格之外，同时得到金额数据（结算金额）：

{ "instrument_id": "MH12034", "input_kind": "yield", "input_value": 0.10,
  "amount_kind": "nominal", "amount_value": 1000000,
  "settlement_date": "2026-06-09", "options": { "round": 6 } }

健康检查

curl https://calc.dev.emrgex.com/v1/health/livez
# {"status":"alive"}

:::tip Performance 若需批量定价，请在一个 /v1/quotes 请求中发送多条报价（即一个批次）。除非你需要每只债券的现金流计划表，否则请关闭 with_cashflows —— 这会让响应体积大幅减小、速度更快。 :::

:::note Authentication 开发环境服务目前为开放状态（无需 API 密钥）。生产环境部署可以启用 HMAC 请求签名。 :::