@bluefin-ai/gfin

Lightweight TypeScript SDK for gfin, a hosted Google Finance data API for builders.

gfin gives you access to Google Finance-style market data without maintaining browser automation or private RPC plumbing: symbol search, quotes, historical prices, financials, earnings, related assets, sentiment, market summaries, news, realtime snapshots, watchlists, and natural-language research through product-native namespaces. Use it for dashboards, agents, notebooks, research tools, watchlists, prototyping, and app backends.

This SDK is intentionally portable: no runtime dependencies, standard fetch, ESM + CommonJS builds, bundled TypeScript declarations, typed errors, and automatic retries.

Docs: https://docs.gfin.dev/typescript-sdk

npm install @bluefin-ai/gfin

Quick Use

import { Client } from "@bluefin-ai/gfin";

const client = new Client();
const apple = client.ticker("AAPL");

const quote = await apple.quote({ exchange: "NASDAQ" });
const history = await apple.history({ exchange: "NASDAQ" });
const answer = await client.research.ask("Why is AAPL moving today?");

console.log(quote.data, history.data, answer.data);

Common Calls

await client.symbols.search("apple");
await client.quotes.get("AAPL", { exchange: "NASDAQ" });
await client.prices.history("AAPL", { exchange: "NASDAQ" });
await client.financials.get("AAPL");
await client.earnings.get("AAPL");
await client.market.movers();
await client.news.latest({ limit: 10 });
await client.realtime.quotes({ entity_ids: ["/m/0cqyw"] });
await client.watchlists.get();

The client is organized around gfin product areas: symbols, quotes, prices, financials, earnings, related, sentiment, market, news, research, realtime, watchlists, and management. Use client.ticker("AAPL") for symbol-scoped quote, details, profile, history, financials, earnings, related-asset, and sentiment calls.

Runtime Support

The package uses the standard Fetch API. In Node, use Node 18+ or pass a custom fetch implementation:

const client = new Client({ fetch: myFetch });

Configuration can come from constructor options or environment variables in Node-like runtimes:

| Option | Environment | Purpose | | --- | --- | --- | | baseUrl | GFIN_BASE_URL | Override https://api.gfin.dev; must be http or https | | contact | GFIN_CONTACT | Send optional support metadata | | apiKey | GFIN_API_KEY | Send email-verified API credentials | | managementToken | GFIN_MANAGEMENT_TOKEN | Manage API keys after email verification |

apiKey is sent as Authorization: Bearer <key> by default. Pass apiKeyHeader: "x-gfin-key" to use X-Gfin-Key instead.

The SDK retries transient 429, 502, 503, and 504 responses by default. Use maxRetries, retryStatuses, backoffFactorMs, maxBackoffMs, and backoffJitter when you need tighter control, or set maxRetries: 0.

Keep API keys on a server when you do not control the runtime.

Auth Helpers

const client = new Client();
await client.management.requestAuthOtp("[email protected]");
const verified = await client.management.verifyAuthOtp("[email protected]", "123456", {
  label: "agent",
});
const verifiedData = verified.data as {
  api_key?: string;
  management_token?: string;
};

const authed = new Client({ apiKey: verifiedData.api_key });
await authed.management.requestLimitIncrease({
  requestedRps: 25,
  useCase: "production agent workload",
  message: "Short traffic description.",
});

All successful calls return the hosted gfin envelope:

type GfinEnvelope<TData = unknown> = {
  data?: TData;
  meta?: Record<string, unknown>;
};

Errors

HTTP errors throw GfinError. HTTP 429 throws GfinRateLimitError; HTTP 503 throws GfinServiceBusyError after retry exhaustion. Error objects include retryAfterSeconds, status, code, payload, and request IDs when provided.