TypeScript SDK

Package: @yfin/sdk on npm

npm install @yfin/sdk

The package ships ESM, CommonJS, and TypeScript declarations. It has no runtime dependencies and uses standard fetch.

For data behavior, see Symbols, Historical Prices, and Missing Data.

TypeScript

import { Client, Ticker, download } from "@yfin/sdk";

const client = new Client({ contact: "you@example.com" });

const quote = await client.quote(["AAPL", "MSFT"]);
const history = await client.history("AAPL", { period: "5d", interval: "1d" });

const aapl = new Ticker("AAPL", client);
const chain = await aapl.optionChain();

const bars = await download(["AAPL", "MSFT"], {
  client,
  period: "5d",
  interval: "1d",
});

JavaScript

ES modules:

import { Client } from "@yfin/sdk";

const client = new Client({ contact: "you@example.com" });
const quote = await client.quote(["AAPL", "MSFT"]);
console.log(quote.data);

CommonJS:

const { Client } = require("@yfin/sdk");

async function main() {
  const client = new Client({ contact: "you@example.com" });
  console.log(await client.history("AAPL", { period: "5d", interval: "1d" }));
}

main();

Runtime Support

The SDK works anywhere standard fetch is available: modern Node, browsers, Cloudflare Workers, Deno, Bun, and test environments that provide or inject fetch.

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

Use Node 18+ or pass a custom fetch function.

Configuration

Pass configuration directly:

const client = new Client({
  contact: "you@example.com",
  apiKey: "yfin_...",
  timeoutMs: 10_000,
});

Node-like runtimes can also use:

export YFIN_CONTACT=you@example.com
export YFIN_API_KEY=yfin_...
export YFIN_BASE_URL=https://api.yfin.dev

Do not ship manual high-volume API keys in browser bundles. Browser use is fine for anonymous or contact-tier calls; keep privileged keys on a server.

REST Client

The TypeScript SDK exposes one method per named REST route, plus raw for advanced calls by endpoint ID.

await client.endpoints();
await client.quote(["AAPL", "MSFT"]);
await client.history("AAPL", { period: "1mo", interval: "1d" });
await client.options("AAPL", { date: "2026-01-16" });
await client.fundamentals("AAPL", { modules: ["price", "summaryDetail"] });
await client.timeseries("AAPL", ["trailingTotalRevenue"]);
await client.search("apple");
await client.screen({ size: 25 });
await client.screen({
  size: 10,
  query: { operator: "EQ", operands: ["sector", "Technology"] },
});
await client.raw("v7.quote", { params: { symbols: "AAPL,MSFT" } });

Errors

HTTP errors throw YfinError. HTTP 429 throws YfinRateLimitError with retryAfterSeconds when retry guidance is available.

import { Client, YfinRateLimitError } from "@yfin/sdk";

const client = new Client({ contact: "you@example.com" });

try {
  await client.history("AAPL", { period: "1mo", interval: "1d" });
} catch (error) {
  if (error instanceof YfinRateLimitError) {
    console.log("retry after", error.retryAfterSeconds);
  }
}

For response schemas and examples, use the API Reference.