发起你的第一个 Narwhal API 请求

通过REST或MCP使用一个密钥访问经济数据、FX、股票、SEC申报、棕榈油价格和日历。

本指南从 CPI 开始，然后在以下位置链接到六个 API 各自可用的参考文档 api.narwhalapi.com.

经济数据覆盖范围

AUS、CAN、DEU、FRA、GBR、JPN、MYS、NLD、SGP 和 USA 均已上线。每次数据请求都需要 Narwhal API 密钥。

免费测试版限制： 3,000 每个 UTC 月的成功请求数，加上 30 每分钟请求数，突发容量为 5。REST 和 MCP 共用相同限额。

设置你的 API 密钥

在其中将密钥作为 Bearer 令牌发送 Authorization 标头——绝不放在 URL 中。创建账户以获取免费密钥，然后阅读身份验证指南，再存储密钥。

终端

export NARWHAL_API_KEY="nw_live_..."

请求官方 CPI

在路径中传入 ISO 三字母国家代码。省略 period 返回最新的完整已接受发布版本。

请求

curl --request GET \
  --url https://api.narwhalapi.com/v1/economics/USA/cpi \
  --header "Authorization: Bearer $NARWHAL_API_KEY"

响应示例

{
  "country": "USA",
  "period": "2026-07",
  "value": "333.918",
  "base_period": "1982-84",
  "base_value": "100",
  "released_on": "2026-08-12"
}

Python 和 JavaScript 示例

在应用中使用相同的环境变量和端点。这些示例使用内置库。

Python 3

import json
import os
from urllib.request import Request, urlopen

request = Request(
    "https://api.narwhalapi.com/v1/economics/USA/cpi",
    headers={"Authorization": "Bearer " + os.environ["NARWHAL_API_KEY"]},
)
with urlopen(request, timeout=30) as response:
    data = json.load(response)
print(data)

JavaScript · Node.js 18+

const key = process.env.NARWHAL_API_KEY;
if (!key) throw new Error("Set NARWHAL_API_KEY first");
const response = await fetch(
  "https://api.narwhalapi.com/v1/economics/USA/cpi",
  { headers: { Authorization: "Bearer " + key }, signal: AbortSignal.timeout(30000) }
);
const data = await response.json();
if (!response.ok) throw new Error(JSON.stringify(data));
console.log(data);

选择你的 API

API	开始带有
经济数据 API	十个国家官方发布机构提供的 CPI、通胀、劳动力、GDP 和贸易数据。
FX API	当前汇率、转换和分页历史记录，每个汇率都带有时间戳。
股票 API	发现普通股工具并获取经拆股调整的日线数据。
公开假日日历 API	已发布的官方数据和文档说明来源、范围、期间与限制。
棕榈油鲜果串（FFB）API	按地区和树龄提供的印度尼西亚官方 FFB 计划。
SEC 申报文件 API	公司搜索、身份和 SEC 申报元数据。

选择国家和指标

每个已上线国家都提供九个最新发布操作和九个对应的历史操作。 Economics API 参考列出每条路径和响应结构。

指标	路径后缀
CPI	`/cpi`
通胀	`/inflation`
失业率	`/unemployment`
劳动力参与率	`/labour-force-participation`
GDP 与增长率	`/gdp` · `/gdp-growth`
贸易、出口、进口	`/trade` · `/trade/exports` · `/trade/imports`

通过 MCP 连接

使用 MCP 客户端时沿用同一个密钥和架构。工具发现会列出你账户在全部六个 API 中可用的操作。请参见该 MCP 指南.

与客户端无关的字段映射

{
  "url": "https://api.narwhalapi.com/mcp",
  "headers": {
    "Authorization": "Bearer YOUR_NARWHAL_API_KEY"
  }
}

通过 MCP 客户端的安全密钥设置替换占位符。普通 JSON 不会自行展开环境变量。

首次 tools/call

{
  "method": "tools/call",
  "params": {
    "name": "fx_get_rates",
    "arguments": { "base": "USD", "currencies": ["EUR", "JPY"] }
  }
}

初始化与 tools/list 不会消耗额度。每次成功的 tools/call 消耗一次请求。

阅读响应

读取每项操作的响应架构。Economics 返回领域对象；Equities 使用 meta/values 适用于时间序列和 count/data 适用于金融工具。

规则	这意味着什么
`period`	官方发布版本所返回的确切月份、季度或年份。
`released_on`	官方发布日期。
十进制字符串	数值表示可避免二进制浮点数带来的意外误差。
缺失数据	不完整或不可用的发布会安全失败；缺失值绝不会变成零。

读取 Narwhal 如何存储和更新官方发布版本.

成功响应中的配额标头

X-Request-IDX-RateLimit-LimitX-RateLimit-RemainingX-RateLimit-Reset

按状态和错误代码处理错误

先检查 HTTP 状态，然后使用 code 在应用逻辑中。 detail 用于日志和调试。该错误和配额指南列出所有公开状态。

RFC 9457 问题响应

{
  "ok": false,
  "type": "https://narwhalapi.com/problems/invalid-query",
  "title": "Invalid query",
  "status": 400,
  "detail": "The request parameters are not valid for this operation.",
  "code": "invalid_query",
  "request_id": "019d1af4-8f33-7b21-91af-ef535f2dcf50",
  "instance": "/v1/economics/USA/cpi"
}

需要密钥帮助吗？联系 Narwhal API.

查看其中的新内容更新日志。

LLM？读取llms.txt.