汇率查询

查询参考汇率（不是交易价格），可取最新值或某一天的值。不同数据源支持的基准货币和更新频率不同，见下方数据源表。

接口	POST /v1/exchange-rate-queries
所需权限	exchange_rate:query
MCP 工具	exchange_rate
计量单位	rates

计量单位出现在 execution.usage.units 中，用于对账和计费。

请求字段

字段	类型	必填	说明
invocation_id	string	是	调用方（市场）生成的调用 ID：同一个 ID 在同一操作上只执行一次，用同一 ID 重试会被拒绝而不会重复计费。1–128 个字符，可用 A-Z a-z 0-9 . _ : -。
provider	string	是	处理本次请求的数据源，按下方数据源表的覆盖范围选择。 可选值：frankfurter, us-treasury
base	string	是	ISO 4217 基准货币，例如 USD、EUR。
quotes	string[]	是	1–20 个 ISO 4217 报价货币。
date	string	否	可选，日期 YYYY-MM-DD；省略时返回最新发布的汇率。

数据源

数据源	区域	说明	限制
frankfurter	EU	Frankfurter（欧洲央行等参考汇率），任意基准货币，每日更新	max_quotes: 20, timeout_seconds: 30
us-treasury	US	美国财政部汇率，基准货币 USD，按季度更新	max_quotes: 20, timeout_seconds: 30

示例

curl

curl -sS https://services.zgi.im/v1/exchange-rate-queries \
  -H "Authorization: Bearer $ZGI_SERVICES_TOKEN" \
  -H 'Content-Type: application/json' \
  -d '{"invocation_id": "docs-1791778521-exchange_rate", "provider": "frankfurter", "base": "USD", "quotes": ["CNY", "EUR"], "date": "2026-10-09"}'

HTTP

POST /v1/exchange-rate-queries HTTP/1.1
Host: services.zgi.im
Authorization: Bearer <token>
Content-Type: application/json

{
  "invocation_id": "docs-1791778521-exchange_rate",
  "provider": "frankfurter",
  "base": "USD",
  "quotes": [
    "CNY",
    "EUR"
  ],
  "date": "2026-10-09"
}

MCP

通过 MCP 调用时，工具参数与 HTTP 请求体完全相同。

request.json

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "exchange_rate",
    "arguments": {
      "invocation_id": "docs-1791778521-exchange_rate",
      "provider": "frankfurter",
      "base": "USD",
      "quotes": [
        "CNY",
        "EUR"
      ],
      "date": "2026-10-09"
    }
  }
}

curl -sS https://services.zgi.im/v1/mcp \
  -H "Authorization: Bearer $ZGI_SERVICES_TOKEN" \
  -H 'Content-Type: application/json' -H 'Accept: application/json, text/event-stream' \
  -H 'MCP-Protocol-Version: 2025-11-25' \
  -d @request.json

返回

以下为一次真实调用的返回，列表只保留前两项，长文本已截断。

{
  "code": 0,
  "message": "success",
  "data": {
    "execution": {
      "id": "exe_01a12e52a9647c6a80db06795b1a868e",
      "invocation_id": "docs-1791778521-exchange_rate",
      "capability": "exchange_rate",
      "operation": "exchange_rate.query",
      "provider": "frankfurter",
      "outcome": "succeeded",
      "error_category": null,
      "error_code": null,
      "usage": {
        "provider_requests": 1,
        "units": [
          {
            "name": "rates",
            "value": 2,
            "source": "measured"
          }
        ]
      },
      "upstream_ref": null,
      "request_id": "req_fda09169da0b3aea3c6190c0",
      "started_at": "2026-10-12T04:15:31.684811913Z",
      "finished_at": "2026-10-12T04:15:32.12019483Z",
      "duration_ms": 435
    },
    "result": {
      "base": "USD",
      "rate_date": "2026-10-09",
      "requested_date": "2026-10-09",
      "rates": [
        {
          "quote": "CNY",
          "rate": 6.693
        },
        {
          "quote": "EUR",
          "rate": 0.89154
        }
      ],
      "unavailable_quotes": [],
      "source": {
        "name": "Frankfurter (central bank reference rates)",
        "kind": "reference"
      },
      "retrieved_at": "2026-10-12T04:15:32.120169681Z"
    }
  }
}