Node.js 환율 API: TypeScript로 Narwhal API 사용하기

설정할 내용

Node.js는 Narwhal REST API를 호출하고 JSON 응답을 읽는 스크립트를 위한 JavaScript 실행 환경입니다. 공통 요청 헬퍼와 여섯 가지 데이터 분야 호출을 모두 갖춘 ES 모듈이 만들어집니다. Narwhal은 하나의 계정과 하나의 API 키로 모든 데이터 API를 이용하며, REST와 MCP도 같은 키를 공유합니다. 여기서의 스크립트는 REST를 사용하고, 키는 환경 변수에서 읽습니다.

API 키 설정

1. 무료 키 만들기 회원가입에서 무료 API 키를 받으세요. 이 스크립트의 모든 데이터 분야 요청은 같은 키로 인증됩니다.
2. 키를 환경 파일에 보관하기 키를 .env 파일에 NARWHAL_API_KEY라는 이름으로 넣으세요. YOUR_KEY를 본인의 키로 바꾸면 되고, 스크립트는 그 값을 process.env.NARWHAL_API_KEY로 읽습니다.
   환경 파일

   NARWHAL_API_KEY=YOUR_KEY

3. ES 모듈과 맞는 Node 버전 사용하기 스크립트는 pull.mjs로 저장하세요. Node 18.17 이상에는 전역 fetch가 있어 REST 호출에 별도 패키지가 필요 없습니다. node --env-file=.env pull.mjs로 .env 파일을 불러오려면 Node 20.6 이상이 필요합니다.

요청 헤더는 Authorization: Bearer YOUR_KEY입니다. 스크립트에서는 헤더 값을 환경 변수에서 가져오고, 기본 URL은 https://api.narwhalapi.com로 유지됩니다. 모든 호출은 공통 헬퍼를 통해 같은 헤더를 사용합니다.

코드로 데이터 가져오기

이 코드를 pull.mjs에 저장하세요. get 헬퍼는 기본 URL과 경로로 URL을 만들고, 전달된 쿼리 매개변수를 붙여 fetch로 GET 요청을 보냅니다. 응답이 성공이 아니면 상태와 응답 텍스트가 담긴 오류를 던집니다. 성공이면 호출하는 코드가 읽을 수 있도록 JSON 응답을 반환합니다.

헬퍼와 분야별 호출은 같은 ES 모듈에 두고, 기본 URL과 헤더는 요청보다 앞서 정의하세요. 매개변수 객체는 각 호출에 속합니다. 캘린더 호출은 국가와 날짜 필터를, CPI 호출은 시작 기간을, FX 호출은 통화를 전달합니다.

const API = "https://api.narwhalapi.com";
const headers = { Authorization: `Bearer ${process.env.NARWHAL_API_KEY}` };

async function get(path, params = {}) {
  const url = new URL(API + path);
  for (const [key, value] of Object.entries(params)) url.searchParams.set(key, value);
  const res = await fetch(url, { headers });
  if (!res.ok) throw new Error(`${res.status} ${await res.text()}`);
  return res.json();
}

const { holidays } = await get("/v1/calendars/holidays/USA/2026");
const { releases } = await get("/v1/economics/calendar", {
  countries: "USA",
  start_date: "2026-11-01",
  end_date: "2026-11-30",
  limit: 100,
});
const { observations } = await get("/v1/economics/USA/cpi/observations", {
  start: "2025-09",
});
const { price } = await get("/v1/commodities/spot/BRENT/USD");
const { rates } = await get("/v1/fx/rates/USD", { currencies: "EUR,IDR" });
const { meetings } = await get("/v1/predictions/policy-paths/federal-reserve");

console.log(holidays.length, holidays[0].name);
console.log(releases.length, observations.at(-1));
console.log(
  "Brent",
  price,
  Object.fromEntries(rates.map((rate) => [rate.currency, rate.rate])),
);
console.log(meetings[0].resolves_at.slice(0, 10), meetings[0].p_hold);

node --env-file=.env pull.mjs를 실행해 키를 불러오고 API를 호출하세요. 각 호출은 출력문에서 쓰는 응답 필드를 추출합니다. 환율에서는 스크립트가 반환된 통화와 환율 항목을 객체로 바꾸고, 예측 응답에서는 회의 날짜와 동결 확률을 읽습니다. 이어지는 분야별 샘플도 같은 get 헬퍼와 헤더를 사용합니다.

가져오기 예약하기

호스트의 cron이나 예약 작업을 사용하세요. cron에서는 명령에 환경 파일 경로와 pull.mjs 경로를 넣으므로, 예약 실행된 스크립트도 process.env.NARWHAL_API_KEY로 키를 쓸 수 있습니다. 명령을 예약해서 실행할 때도 --env-file 옵션에는 Node 20.6 이상이 필요합니다.

0 7 * * * node --env-file=/path/.env /path/pull.mjs

/path/.env와 /path/pull.mjs를 본인 파일의 경로로 바꾸세요. 요청 예약에 대한 자세한 내용은 매일 데이터 가져오기 예약하기를 참고하세요.

Node.js에서 공휴일 사용하기

2026년 미국 공휴일을 요청하고 holidays 배열을 읽으세요. 각 공휴일에는 date와 name이 있으며, 샘플은 배열 길이와 첫 번째 공휴일 이름을 출력합니다. 2026년 10월 24일 기준으로 응답에는 2026년 미국 공휴일 11개가 들어 있었습니다. 직접 만드는 출력에서 날짜를 쓰려면 공휴일 항목의 date를 읽으세요. name 필드는 그 날짜에 해당하는 공휴일 이름을 알려 줍니다.

const { holidays } = await get(
  "/v1/calendars/holidays/USA/2026"
);
console.log(holidays.length, holidays[0].name);

Node.js에서 발표일 사용하기

미국 경제 캘린더를 2026년 11월 기간으로 요청하고 releases를 읽으세요. 각 항목에는 at, period, topic, status가 있어 발표일을 주제 및 기간과 함께 읽을 수 있습니다. 2026년 10월 24일 기준으로 이 2026년 11월 기간에는 발표가 31건 있었습니다. 날짜 필터는 캘린더 요청에 속하고, period 필드는 각 발표 항목에 속합니다. 출력에 주제와 상태가 필요하면 같은 항목에서 읽으세요.

const { releases } = await get("/v1/economics/calendar", {
  countries: "USA", start_date: "2026-11-01", end_date: "2026-11-30", limit: 100
});
console.log(releases.length);

Node.js에서 경제 데이터 사용하기

start 매개변수를 붙여 미국 CPI 관측값을 요청하고 observations를 읽으세요. 각 관측값에는 period와 value가 있으며, 샘플은 반환된 배열의 마지막 항목을 읽습니다. 2026년 10월 24일 기준으로 2026-09 기간의 CPI 값은 336.940이었습니다. Narwhal 경제 데이터에는 인플레이션, GDP, 수익률도 포함됩니다. 관측값을 읽을 때는 기간을 값과 함께 보관해, 출력에서 그 값이 어느 CPI 기간에 속하는지 알 수 있게 하세요. 요청의 시작 기간은 쿼리 매개변수로 전달합니다.

const { observations } = await get(
  "/v1/economics/USA/cpi/observations", { start: "2025-09" }
);
console.log(observations.at(-1));

Node.js에서 원자재 현물 가격 사용하기

Brent를 USD로 요청하고 응답의 price 필드를 읽으세요. 2026년 10월 24일 기준으로 Brent는 배럴당 116.8809달러였습니다. 현물 코드에는 예를 들어 XAU, XAG, XPT, XPD, XCU, BRENT, WTI가 있습니다. 이 샘플은 요청 경로에 BRENT와 USD를 사용합니다. 여기서의 코드는 JSON 응답에서 단일 price 필드를 읽습니다. 원자재 코드와 통화는 공통 요청 헬퍼에 전달하는 URL의 일부입니다.

const { price } = await get(
  "/v1/commodities/spot/BRENT/USD"
);
console.log("Brent", price);

Node.js에서 환율 사용하기

USD를 기준으로 EUR와 IDR을 요청하고 rates를 읽으세요. 각 항목에는 currency와 rate가 있으며, 소수 환율은 문자열입니다. 2026년 10월 24일 기준으로 USD/EUR은 0.89342, USD/IDR은 18107.8이었습니다. 샘플은 각 통화를 반환된 환율의 객체 속성으로 사용합니다. 요청하는 통화는 쿼리 매개변수이고, 기준 통화는 경로에 들어 있습니다. 반환된 배열을 그대로 쓸 때는 각 환율과 함께 통화 필드도 읽으세요.

const { rates } = await get(
  "/v1/fx/rates/USD", { currencies: "EUR,IDR" }
);
console.log(Object.fromEntries(rates.map((rate) => [rate.currency, rate.rate])));

Node.js에서 예측 시장 확률 사용하기

연방준비제도 정책 경로를 요청하고 meetings를 읽으세요. 각 회의에는 resolves_at, p_cut, p_hold, p_hike가 있습니다. 2026년 10월 24일 기준으로 2026년 10월 28일 회의의 동결 확률은 0.9188이었습니다. 샘플은 첫 번째 회의 항목의 날짜를 동결 확률과 함께 출력합니다. 인하 또는 인상 확률이 필요하면 회의 항목의 p_cut 또는 p_hike를 사용하세요. 확률이 어느 회의의 것인지 알 수 있도록 resolves_at을 확률과 함께 보관하세요.

const { meetings } = await get(
  "/v1/predictions/policy-paths/federal-reserve"
);
console.log(meetings[0].resolves_at.slice(0, 10), meetings[0].p_hold);

TypeScript 타입이 필요한가요?

읽는 응답 필드에만 타입을 지정하세요. FX 예시에서 응답의 형태는 { rates: { currency: string; rate: string }[] }입니다. 소수 값은 문자열이므로 TypeScript 타입에서 rate에는 string을 사용하세요.

왜 await가 최상위에 있나요?

ES 모듈에서는 최상위 await를 쓸 수 있어서, 샘플은 각 get 호출을 그대로 기다립니다. 여기서 보여 준 .mjs 확장자를 쓰거나, JavaScript ES 모듈로 "type": "module"을 설정하세요.