Make your first Narwhal API request

Use one key for Economics, FX, palm-oil prices, and Public Holidays through REST or MCP.

This guide starts with CPI, then links to a working reference for each of the four APIs at api.narwhalapi.com.

Economics coverage

36 Countries: AUS, AUT, BEL, CAN, CHL, COL, CZE, DEU, DNK, ESP, EST, FIN, FRA, GBR, HRV, IRL, ITA, JPN, LTU, LUX, LVA, MEX, MYS, NLD, NOR, NZL, PAK, PHL, POL, PRT, QAT, SAU, SGP, SVN, SWE, USA. Coverage varies by operation and country. Each operation lists its supported countries. Every data request needs a Bearer key.

Free beta limits: 3,000 successful requests per UTC month, plus 30 requests per minute. REST and MCP share the same limits.

Set up your API key

Send the key as a Bearer token in the Authorization header—never in the URL. Create an account to get a free key, then read the authentication guide before storing it.

Terminal

export NARWHAL_API_KEY="nw_live_..."

Request official CPI

Pass the ISO three-letter country code in the path. Omitting period returns the latest accepted complete release.

Request

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

Example response

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

Python and JavaScript examples

Use the same environment variable and endpoint in your application. These examples use built-in libraries.

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);

Choose your API

API	Start with
Economics API	CPI, inflation, labour, GDP, and trade data from official publishers. Coverage varies by country and indicator.
FX API	Current rates, conversion, and paginated history with a timestamp for every rate.
Public Holidays API	Published public holidays with national, regional, and observed-day scope.
Palmoil API	CPO and FFB prices from Indonesia and Malaysia, with native units and history.

Choose a country and indicator

Latest-release and matching history operations are available, with indicator coverage varying by country. The Economics API reference lists every path and response shape.

Indicator	Path suffix
CPI	`/cpi`
Inflation	`/inflation`
Unemployment	`/unemployment`
Labour-force participation	`/labour-force-participation`
GDP and growth	`/gdp` · `/gdp-growth`
Trade, exports, imports	`/trade` · `/trade/exports` · `/trade/imports`

Connect through MCP

Use the same key and schemas with an MCP client. Tool discovery lists the operations available to your account across all four APIs. See the MCP guide.

Client-neutral field map

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

Replace the placeholder through your MCP client's secure secret setting. Plain JSON does not expand environment variables by itself.

First tools/call

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

Initialization and tools/list do not consume quota. Each successful tools/call consumes one request.

Read the response

Read each operation’s response schema before integrating.

Rule	What it means
`period`	The exact month, quarter, or year returned by the official release.
`released_on`	The official publication date.
Decimal strings	Values avoid binary floating-point surprises.
Missing data	Incomplete or unavailable releases fail closed; missing never becomes zero.

Read how Narwhal stores and updates official releases.

Quota headers on successful responses

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

Handle errors by status and code

Check the HTTP status first, then use code in application logic. detail is for logs and debugging. The errors and quota guide lists every public status.

RFC 9457 problem response

{
  "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"
}

Need help with a key? Contact Narwhal API.

See what's new in the changelog.

LLM? Read llms.txt.