開始使用

Base URL 與慣例

Base 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 請求簽章。 :::