FlashAlpha Logo
SDKs JavaScript

FlashAlpha JavaScript SDK

Official JavaScript & TypeScript SDK. Runs in Node 18+, Deno, Bun, Cloudflare Workers, and modern browsers — zero dependencies, native fetch.

Install
npm install flashalpha
Version
0.3.0 · Node 18+
GitHub npm Zero runtime deps CommonJS TypeScript types bundled

What the SDK gives you

Full endpoint coverage

Every REST endpoint — market data, exposure (GEX/DEX/VEX/CHEX), volatility, pricing, screener, account — is a method on the client.

Zero dependencies

Uses native fetch. Works unchanged in Node 18+, Bun, Deno, Cloudflare Workers, Vercel Edge, and browsers.

TypeScript-first

Type declarations ship with the package. IDE autocomplete on every method and option.

Typed error classes

AuthenticationError, TierRestrictedError, RateLimitError, NotFoundError, ServerError — use instanceof to branch.

Custom fetch injection

Override fetch to add logging, retries, caching, or a testing mock — without forking the client.

Live options screener

Build filter/sort/select queries as plain objects. Alpha-tier formulas and cascading filters included.

Install

npm install flashalpha
# or
yarn add flashalpha
# or
pnpm add flashalpha

Requires Node 18+ (for native fetch). No Polyfill needed in browsers or serverless runtimes.

Quick start

import { FlashAlpha } from 'flashalpha';

const fa = new FlashAlpha('YOUR_API_KEY');

// Gamma exposure for SPY
const gex = await fa.gex('SPY');
console.log(gex.net_gex, gex.gamma_flip);

// Key support / resistance levels
const { levels } = await fa.exposureLevels('SPY');
console.log(levels.call_wall, levels.put_wall);

// BSM greeks for a single contract
const g = await fa.greeks({ spot: 655, strike: 660, dte: 7, sigma: 0.18, type: 'call' });
console.log(g.delta, g.gamma, g.theta);

// Plan & quota usage
console.log(await fa.account());

Live options screener

// Vol scanner with an inline formula (Alpha tier)
const result = await fa.screener({
  formulas: [{ alias: 'iv_premium', expression: 'atm_iv - rv_20d' }],
  filters:  { formula: 'iv_premium', operator: 'gte', value: 5 },
  sort:     [{ formula: 'iv_premium', direction: 'desc' }],
  select:   ['symbol', 'atm_iv', 'rv_20d', 'iv_premium'],
  limit:    20,
});

for (const row of result.data) {
  console.log(row.symbol, row.iv_premium);
}

Common recipes

TypeScript: typed screener row

type Row = { symbol: string; price: number; net_gex: number; regime: string };
type ScreenerResp = { meta: { returned_count: number }; data: Row[] };

const res = (await fa.screener({
  sort:   [{ field: 'net_gex', direction: 'desc' }],
  select: ['symbol', 'price', 'net_gex', 'regime'],
  limit:  10,
})) as ScreenerResp;

res.data.forEach(r => console.log(r.symbol, r.net_gex));

Next.js server action / route handler

// app/api/gex/[symbol]/route.ts
import { FlashAlpha } from 'flashalpha';

const fa = new FlashAlpha(process.env.FLASHALPHA_KEY!);

export async function GET(_req: Request,
                         { params }: { params: { symbol: string } }) {
  const gex = await fa.gex(params.symbol);
  return Response.json(gex);
}

Testing with a mocked fetch

const fakeFetch = async (_url: string, _init?: RequestInit) =>
  new Response(JSON.stringify({ net_gex: 123, gamma_flip: 650 }),
               { status: 200, headers: { 'content-type': 'application/json' }});

const fa = new FlashAlpha('test-key', { fetch: fakeFetch });
expect(await fa.gex('SPY')).toEqual({ net_gex: 123, gamma_flip: 650 });

Method catalog

CategoryMethodsTier
Market datastockQuote, optionQuote, stockSummary, surfaceFree / Growth
Historical replay (point-in-time)historicalStockQuote, historicalOptionQuote, plus the full live API mirrored on historical.flashalpha.com via new FlashAlpha({ apiKey, baseUrl: "https://historical.flashalpha.com" }) with at paramAlpha
Exposure (basic)gex, exposureLevelsFree+ (equities); Basic+ for ETFs & indexes
Exposure (Greeks)dex, vex, chex, maxpainBasic+
Exposure (Growth)exposureSummary, narrative, zeroDte, exposureHistoryGrowth+
Pricinggreeks, iv, kellyFree / Growth
Volatilityvolatility, advVolatilityGrowth / Alpha
ScreenerscreenerGrowth+
Referencetickers, options, symbolsFree+
Accountaccount, healthFree+

Error handling

import {
  FlashAlpha,
  FlashAlphaError,
  AuthenticationError,
  TierRestrictedError,
  NotFoundError,
  RateLimitError,
  ServerError,
} from 'flashalpha';

const fa = new FlashAlpha('YOUR_API_KEY');

try {
  const out = await fa.narrative('SPY');
} catch (e) {
  if (e instanceof TierRestrictedError) {
    console.log(`Upgrade to ${e.requiredPlan}`);
  } else if (e instanceof RateLimitError) {
    console.log(`Retry after ${e.retryAfter}s`);
  } else if (e instanceof FlashAlphaError) {
    console.log(`API error ${e.statusCode}: ${e.message}`);
  } else {
    throw e;
  }
}
HTTPClassProperties
401AuthenticationError—
403TierRestrictedErrorcurrentPlan, requiredPlan
404NotFoundError—
429RateLimitErrorretryAfter
5xxServerErrorstatusCode
otherFlashAlphaErrorstatusCode

Client configuration

const fa = new FlashAlpha('YOUR_API_KEY', {
  baseUrl: 'https://lab.flashalpha.com',   // default
  timeout: 30_000,                          // milliseconds
  fetch:   customFetch,                     // optional override
});

Injecting a custom fetch is the easiest way to add request-level retries, logging, or a test double. The override receives the same (url, init) signature as global fetch.

Links

Ready to build?

Get your free API key and start pulling live options data in 30 seconds.