Skip to content
oneapi.finance API Reference

TypeScript types

These interfaces mirror the wire format of every endpoint, in the same camelCase shape the API actually returns. Drop the file into your project and import as needed.

oneapi.types.ts
// Wire format types for oneapi.finance v1.
// Mirrors packages/oneapi_core/oneapi_core/responses/*.


export type Interval =
  | "1min" | "5min" | "15min" | "30min" | "45min"
  | "1h" | "2h" | "4h"
  | "1day" | "1week" | "1month";


// ---------- Common ----------
export interface ResponseMeta {
  source?: string | null;
  fetched_at?: string | null;
}


export interface ErrorResponse {
  code:
    | "rate_limit" | "unauthenticated" | "forbidden"
    | "not_found"  | "bad_request"     | "upstream_failure"
    | "internal";
  message: string;
  status: number;
  details?: Record<string, unknown> | null;
}


// ---------- Quote ----------
export interface Quote {
  symbol: string;
  name?: string | null;
  exchange?: string | null;
  currency?: string | null;
  price?: number | null;
  open?: number | null;
  high?: number | null;
  low?: number | null;
  previousClose?: number | null;
  change?: number | null;
  changePercent?: number | null;
  volume?: number | null;
  avgVolume?: number | null;
  high52Week?: number | null;
  low52Week?: number | null;
  timestamp?: string | null;
  meta?: ResponseMeta | null;
}


export interface QuotesResponse {
  quote?: Quote | null;
  quotes?: Record<string, Quote> | null;
  data_issues?: string[] | null;
}


// ---------- Time series ----------
export interface TimeSeriesBar {
  datetime: string;
  open?: number | null;
  high?: number | null;
  low?: number | null;
  close?: number | null;
  volume?: number | null;
}


export interface TimeSeriesResponse {
  symbol: string;
  interval: Interval;
  currency?: string | null;
  exchange?: string | null;
  values: TimeSeriesBar[];
}


// ---------- Statistics ----------
export interface StatisticsResponse {
  marketCap?: number | null;
  enterpriseValue?: number | null;
  trailingPe?: number | null;
  forwardPe?: number | null;
  pegRatio?: number | null;
  priceToSales?: number | null;
  priceToBook?: number | null;
  profitMargin?: number | null;
  operatingMargin?: number | null;
  roe?: number | null;
  roa?: number | null;
  revenueTtm?: number | null;
  eps?: number | null;
  ebitda?: number | null;
  beta?: number | null;
  fiftyTwoWeekHigh?: number | null;
  fiftyTwoWeekLow?: number | null;
  fiftyDayMa?: number | null;
  twoHundredDayMa?: number | null;
  sharesOutstanding?: number | null;
  dividendYield?: number | null;
  payoutRatio?: number | null;
  exDividendDate?: string | null;
}


// ---------- Profile ----------
export interface ProfileResponse {
  symbol: string;
  name?: string | null;
  exchange?: string | null;
  sector?: string | null;
  industry?: string | null;
  description?: string | null;
  website?: string | null;
  ceo?: string | null;
  employees?: number | null;
  country?: string | null;
  address?: string | null;
  phone?: string | null;
  isin?: string | null;
  figi?: string | null;
  cik?: string | null;
}


// ---------- Dividends ----------
export interface DividendEntry {
  ex_date: string;
  amount: number;
  currency?: string | null;
  declaration_date?: string | null;
  payment_date?: string | null;
  record_date?: string | null;
}


export interface SymbolDividends {
  annualDividend?: number | null;
  dividendYield?: number | null;
  payoutRatio?: number | null;
  history: DividendEntry[];
}


export interface DividendsResponse {
  dividends: Record<string, SymbolDividends>;
}


// ---------- Splits ----------
export interface SplitEntry {
  date: string;
  ratio_from: number;
  ratio_to: number;
}


export interface SplitsResponse {
  symbol: string;
  splits: SplitEntry[];
}


// ---------- Symbol search ----------
export interface SymbolSearchResult {
  symbol: string;
  name?: string | null;
  exchange?: string | null;
  type?: string | null;
  country?: string | null;
  currency?: string | null;
  isin?: string | null;
  figi?: string | null;
  score?: number | null;
}


export interface SymbolSearchResponse {
  symbols: SymbolSearchResult[];
}


// ---------- FX ----------
export interface FxBar {
  datetime: string;
  open?: number | null;
  high?: number | null;
  low?: number | null;
  close?: number | null;
}


export interface FxPair {
  pair: string;
  current?: number | null;
  previous?: number | null;
  history?: FxBar[] | null;
}


export interface FxResponse {
  rates: Record<string, FxPair>;
}

Type-safe usage

import { OneApi } from "./oneapi.js";
import type { QuotesResponse, StatisticsResponse } from "./oneapi.types.js";


const api = new OneApi();


const quotes = (await api.quote({ symbols: ["AAPL", "MSFT"] })) as QuotesResponse;
for (const [symbol, q] of Object.entries(quotes.quotes ?? {})) {
  console.log(`${symbol} ${q.price} (${q.currency})`);
}


const stats = (await api.statistics("AAPL")) as StatisticsResponse;
console.log(`P/E ${stats.trailingPe}, ROE ${stats.roe}`);

If you want stronger inference, replace the as casts with zod-validated parses:

import { z } from "zod";


const QuotesResponseSchema = z.object({
  quote: z.object({
    symbol: z.string(),
    price: z.number().nullable(),
    /* ... */
  }).optional(),
});


const body = QuotesResponseSchema.parse(await api.quote({ symbol: "AAPL" }));

See also