quantgist-js

Official TypeScript SDK for the QuantGist macro economic event API — zero runtime dependencies, dual ESM + CJS, browser-compatible.

Installation

npm install quantgist-js
# or
pnpm add quantgist-js

30-second quickstart

import { QuantGistClient } from "quantgist-js";

const client = new QuantGistClient({ apiKey: "qg_live_..." });

// Macro events
const { data, meta } = await client.getEvents({ impact: "high" });
for (const event of data) {
  console.log(`${event.release_time} | ${event.country} | ${event.title}`);
}

// Upcoming earnings
const earnings = await client.getEarningsUpcoming(10);
for (const e of earnings.data) {
  console.log(`${e.report_date} | ${e.ticker} | est EPS ${e.eps_estimate}`);
}

// Markets overview
const markets = await client.getMarketsOverview();
for (const q of markets.data) {
  console.log(`${q.symbol}: ${q.close} (${q.change_pct?.toFixed(2)}%)`);
}

// Changelog (no auth required)
const { data: log } = await client.getChangelog();
console.log(log[0].version, log[0].summary);

Get your free API key at quantgist.com/dashboard.

Macro Shortcuts

The /v1/macro/* endpoints provide trader-friendly aliases for common macro events:

const API_KEY = 'your_api_key';
const BASE = 'https://api.quantgist.com/v1';
const headers = { 'X-API-Key': API_KEY };

// Get the latest released NFP value
const nfp = await fetch(`${BASE}/macro/latest?event=NFP`, { headers }).then(r => r.json());
console.log(`NFP: ${nfp.actual} (forecast: ${nfp.forecast})`);

// Get next CPI release
const cpi = await fetch(`${BASE}/macro/upcoming?event=CPI`, { headers }).then(r => r.json());
console.log(`Next CPI: ${cpi.release_time}`);

// Get upcoming macro calendar (14 days)
const calendar = await fetch(`${BASE}/macro/calendar?events=CPI,NFP,FOMC&days=14`, { headers }).then(r => r.json());
calendar.forEach(group => console.log(`${group.event}: ${group.next_release}`));

Supported aliases: NFP, CPI, PCE, FOMC, GDP, UNEMPLOYMENT, RETAIL_SALES, PPI, ISM, ECB, HICP

---

Browser / Next.js usage

The SDK uses only the native fetch API — no Node.js-specific modules. It works in any modern browser, Next.js App Router client components, and Cloudflare Workers.

In browser environments you must pass apiKey explicitly (there is no process.env in the browser):

// Next.js client component
const client = new QuantGistClient({
  apiKey: process.env.NEXT_PUBLIC_QUANTGIST_API_KEY!,
});

In Node 20+ you can set the QUANTGIST_API_KEY environment variable and omit apiKey from the constructor:

// Node — reads QUANTGIST_API_KEY automatically
const client = new QuantGistClient();

API reference

new QuantGistClient(options?)

Option	Type	Default	Description
apiKey	string	process.env.QUANTGIST_API_KEY	Your QuantGist API key. Required in browser environments.
baseUrl	string	https://api.quantgist.com/v1	Override the API base URL (useful for testing).
timeout	number	30000	Request timeout in milliseconds.

Throws AuthenticationError if no API key is found.

---

Macro events

Method	Returns	Description
getEvents(params?)	Promise<EventsResponse>	Filtered, paginated macro event list.
getEvent(id)	Promise<Event>	Single event by ID.

getEvents params: from, to, country, currency, impact, symbol, limit, page.

---

Earnings

Method	Returns	Description
getEarnings(params?)	Promise<EarningsResponse>	Filtered, cursor-paginated earnings list.
getEarningsUpcoming(limit?)	Promise<EarningsResponse>	Next N upcoming reports.
getEarningsForTicker(ticker, params?)	Promise<EarningsResponse>	Earnings history for one ticker.
getEarningsSummary(ticker)	Promise<EarningsSummary>	Beat/miss/in-line counts.
getEarningsHistory(ticker, params?)	Promise<EarningsResponse>	Paginated history — Pro+ required.
getEarningsSurprises(limit?)	Promise<EarningsSurprise[]>	Largest cross-market EPS surprises.
getEarningsMovers(limit?)	Promise<EarningsMover[]>	Events ranked by price/volume impact.
getEarningsWeekCalendar()	Promise<EarningsWeekCalendar>	Week-ahead calendar grouped by day.
getEarningsSeasonSummary()	Promise<EarningsSeasonSummary>	Index-level aggregate for current season.

getEarnings params: ticker, from, to, sector, beat_miss, cursor, limit.

Key fields on EarningsEvent:

interface EarningsEvent {
  ticker: string;
  company_name: string;
  report_date: string;          // ISO date
  eps_estimate: number | null;
  eps_actual: number | null;
  revenue_estimate: number | null;
  revenue_actual: number | null;
  surprise_pct: number | null;
  beat_miss: "beat" | "miss" | "in-line" | null;
  sec_filing_url: string | null;        // SEC EDGAR 8-K URL
  sec_accession_number: string | null;  // e.g. "0000320193-26-000001"
  sec_filed_at: string | null;          // ISO date filed with SEC
  field_sources: Record<string, string>; // provenance per field
}

---

Markets

Method	Returns	Description
getMarketsOverview()	Promise<MarketsOverviewResponse>	Major indices overview (EOD Stooq).
getMarketsSectors()	Promise<MarketsOverviewResponse>	Sector ETF quotes.
getMarketsCurrencies()	Promise<MarketsOverviewResponse>	Currency pair quotes.
getMarketsCommodities()	Promise<MarketsOverviewResponse>	Commodity quotes.
getMarketQuote(symbol)	Promise<MarketQuote>	Single symbol EOD quote.

---

Changelog

Method	Returns	Description
getChangelog()	Promise<ChangelogResponse>	Public API changelog — no elevated plan required.

Error handling

All errors extend QuantGistError which carries a statusCode property.

import {
  QuantGistClient,
  AuthenticationError,
  RateLimitError,
  NotFoundError,
  PlanUpgradeRequired,
  QuantGistError,
} from "quantgist-js";

try {
  const { data } = await client.getEvents({ impact: "high" });
} catch (err) {
  if (err instanceof AuthenticationError) {
    // 401 — invalid or missing API key
    console.error("Check your API key");
  } else if (err instanceof RateLimitError) {
    // 429 — slow down requests
    console.error("Rate limit hit, retry later");
  } else if (err instanceof NotFoundError) {
    // 404
    console.error("Event not found");
  } else if (err instanceof PlanUpgradeRequired) {
    // 402 — feature requires a paid plan
    console.error("Upgrade at quantgist.com/pricing");
  } else if (err instanceof QuantGistError) {
    // Other API errors
    console.error(`API error ${err.statusCode}: ${err.message}`);
  }
}

Links

• Full API docs: quantgist.com/docs
• Get an API key: quantgist.com/dashboard
• Pricing: quantgist.com/pricing
• Python SDK: quantgist-python

License

MIT — see LICENSE.