六个 Currency 契约的输入及失败语义

换算金额必须是数值

convert 要求 from 和 to 属于文档支持的币种枚举。amount 是 JSON 数值，默认 1，必须有限且大于零，上限为 1,000,000,000。字符串金额不被接受；可选 date 指定历史参考日期。

fromtoamountdate

日期与目标代码规则

输入日期采用 YYYY-MM-DD 格式，必须是真实日历日期，范围为 1999-01-04 至当天 UTC 日期。historical 必填 date；timeseries 和 fluctuation 必填顺序正确的 start/end，含首尾最多 31 日。symbols 为无空格、英文逗号分隔的 1–10 个不重复大写代码，默认 USD,GBP,JPY。

startendsymbols

读取实际发布日

historical 返回 base、date 和 rates；requested_date 可说明周末或节假日回退。latest 还可能包含 amount 和 Unix timestamp。convert 返回来源币种、目标币种、金额、汇率、结果和日期。可选字段仅在存在时返回。

requested_datetimestampresult

区间标签不等于每日观测

timeseries 的 rates 按日期组织币种汇率。区间标签可能是 start/end 或 start_date/end_date，两组均被接受。stop_reason 非空时表示序列提前截止，并非完整结果。fluctuation 包含起止汇率、带符号变化值及 change_pct，比较前要检查实际端点日期。currencies 返回日期、EUR 基准、数量及代码名称映射。

ratesstop_reasonstart_dateend_datechange_pctcount

失败与来源署名

ok:true 的响应所携带的 data 已通过该操作的输出 schema 校验。未通过校验的结果返回 RESULT_INVALID（502）：结果未知，价格先被预留，随后释放，绝不扣费。操作报告未成功时返回 REQUEST_NOT_FULFILLED（502），不扣费。SERVICE_UNAVAILABLE 表示服务端的状况，不是钱包余额不足。OPERATION_TIMEOUT、RESULT_INVALID 等结果未知的情况，不能自动换新的 Idempotency-Key 重放可能收费的请求。结果附带来源署名时，会在 meta.sourceAttribution 中返回。

okdatasourceAttribution

最近参考汇率

POST /api/v1/currency/latest

使用文档中的平铺 JSON 对象。字段保留在顶层，不要再包裹一层 body。

{
  "base": "EUR",
  "symbols": "USD,GBP,JPY"
}

{
  "base": "EUR",
  "date": "2024-01-05",
  "rates": {
    "USD": 1.1,
    "GBP": 0.85,
    "JPY": 160
  },
  "amount": 1
}

金额换算

POST /api/v1/currency/convert

使用文档中的平铺 JSON 对象。字段保留在顶层，不要再包裹一层 body。

{
  "from": "USD",
  "to": "EUR",
  "amount": 100
}

{
  "from": "USD",
  "to": "EUR",
  "amount": 100,
  "rate": 0.9,
  "result": 90,
  "date": "2024-01-05"
}

历史参考日

POST /api/v1/currency/historical

使用文档中的平铺 JSON 对象。字段保留在顶层，不要再包裹一层 body。

{
  "date": "2024-01-06",
  "base": "EUR",
  "symbols": "USD,GBP"
}

{
  "base": "EUR",
  "date": "2024-01-05",
  "requested_date": "2024-01-06",
  "rates": {
    "USD": 1.1,
    "GBP": 0.85
  }
}

短期汇率序列

POST /api/v1/currency/timeseries

使用文档中的平铺 JSON 对象。字段保留在顶层，不要再包裹一层 body。

{
  "start": "2024-01-02",
  "end": "2024-01-05",
  "base": "EUR",
  "symbols": "USD"
}

{
  "base": "EUR",
  "start": "2024-01-02",
  "end": "2024-01-05",
  "rates": {
    "2024-01-02": {
      "USD": 1.1
    },
    "2024-01-03": {
      "USD": 1.11
    },
    "2024-01-04": {
      "USD": 1.09
    },
    "2024-01-05": {
      "USD": 1.1
    }
  }
}

区间端点变化

POST /api/v1/currency/fluctuation

使用文档中的平铺 JSON 对象。字段保留在顶层，不要再包裹一层 body。

{
  "start": "2024-01-02",
  "end": "2024-01-05",
  "base": "EUR",
  "symbols": "USD"
}

{
  "base": "EUR",
  "start": "2024-01-02",
  "end": "2024-01-05",
  "start_date": "2024-01-02",
  "end_date": "2024-01-05",
  "rates": {
    "USD": {
      "start_rate": 1.1,
      "end_rate": 1.11,
      "change": 0.01,
      "change_pct": 0.9090909091
    }
  }
}

当前币种名称

POST /api/v1/currency/currencies

使用文档中的平铺 JSON 对象。字段保留在顶层，不要再包裹一层 body。

{}

{
  "date": "2024-01-05",
  "base": "EUR",
  "count": 3,
  "currencies": {
    "USD": "US dollar",
    "GBP": "Pound sterling",
    "JPY": "Japanese yen"
  }
}