@bluefin-ai/tvfin

Lightweight TypeScript SDK for tvfin, a hosted TradingView data API for builders.

tvfin gives you access to TradingView market data without running your own browser or scraper stack: symbol search, news, economic calendars, earnings and dividend events, screeners, options data, public ideas, and public scripts 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 builds, bundled TypeScript declarations, automatic transient retries, and a public surface that follows tvfin routes rather than upstream provider endpoint names.

Docs: https://docs.tvfin.bluedoor.sh

npm install @bluefin-ai/tvfin

Quick Use

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

const client = new Client();

const symbols = await client.symbols.search("apple", { exchange: "NASDAQ" });
const news = await client.news.forSymbol("NASDAQ:AAPL");
const screen = await client.screeners.search("america", { columns: ["name", "close"], limit: 5 });
const chain = await client.options.chain("AAPL", { limit: 10 });

console.log(symbols.data, news.data, screen.data, chain.data);

Common Calls

await client.symbols.search("tesla", { type: "stock" });
await client.news.headlines({ lang: "en" });
await client.news.flow({ market: "stocks" });
await client.calendar.economic({ country: "US" });
await client.events.earnings({ limit: 25, columns: ["name", "earnings_release_date"] });
await client.screeners.metadata("america");
await client.screeners.search("america", { limit: 25, columns: ["name", "close", "volume"] });
await client.screeners.global({ markets: "america,crypto", limit: 25 });
await client.options.impliedVolatility("AAPL");
await client.options.underlyingAggregates("AAPL");
await client.ideas.list({ symbol: "AAPL" });
await client.scripts.list({ symbol: "AAPL" });

The client is organized around tvfin product areas: symbols, news, calendar, events, screeners, options, ideas, scripts, and management.

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 | TVFIN_BASE_URL | Override https://api.tvfin.bluedoor.sh; must be http or https | | contact | TVFIN_CONTACT | Send optional support metadata | | apiKey | TVFIN_API_KEY | Send email-verified API credentials | | managementToken | TVFIN_MANAGEMENT_TOKEN | Manage API keys after email verification |

apiKey is sent as Authorization: Bearer <key> by default. Pass apiKeyHeader: "x-tvfin-key" to use X-Tvfin-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.",
});

const managed = new Client({
  managementToken: verifiedData.management_token,
});
const keys = await managed.management.keys.list();
const created = await managed.management.keys.create({ label: "batch job" });
const createdData = created.data as { key?: { id?: string } };
if (createdData.key?.id) {
  await managed.management.keys.rotate(createdData.key.id);
}

All successful calls return the hosted tvfin envelope:

type TvfinEnvelope<TData = unknown> = {
  data?: TData;
  meta?: {
    provider?: "tradingview";
    generated_at?: string;
    route?: string;
  };
};

Errors

HTTP errors throw TvfinError. HTTP 429 throws TvfinRateLimitError; HTTP 503 throws TvfinServiceBusyError after retry exhaustion. Error objects include retryAfter, status, requestId, and the response payload.