tn-financial-data

Hosted US equity, macro, SEC filings, and earnings transcript coverage for agents.

tn-financial-data is the published agent-facing surface for the hosted API:

• tn-financial-data query ...
• tn-financial-data skill ...
• tn-financial-data describe opencli
• a typed TypeScript client from tn-financial-data

The package does not bundle your API key. The installed package does not read project-local .env files. Pass credentials with CLI flags or environment variables in the invoking process.

Best Path

Use the package in one of three ways:

• Direct CLI: best when a human or agent can just run commands
• Packaged skill bundle: best for Claude Code or OpenCode style agent runtimes
• describe opencli: best for tool-aware runtimes that want a machine-readable command contract

If the goal is fast agent activation, the usual order is:

1. install the package
2. expose TN_FINANCIAL_DATA_API_KEY to the process that will run the agent
3. verify one successful query
4. install or print the packaged skill, or load describe opencli

Requires API Access

Installing the package is not enough for live reads.

• You need a valid TN_FINANCIAL_DATA_API_KEY or --api-key <key>
• skill install only installs the packaged skill bundle; it does not provision API access
• the agent or CLI process itself must see the API key in its runtime environment
• the default hosted base URL is https://api.truenorth-financial.ai/v1

This package is the hosted agent-facing surface only. The repo's website, local playground, self-hosting runtime, and local TradingView prototype tooling are intentionally outside the npm contract.

Features

• Company facts, financials, ETF profiles and holdings, prices, canonical issuer news, insider trades, ownership, earnings transcript structure and coverage, stored macro history, and raw SEC filings through one hosted API
• Multi-ticker resolve and snapshot reads for lower-latency agent workflows
• Earnings calendar, dividends, and stock splits through the same hosted read contract
• Canonical issuer-scoped news plus cross-ticker news-search over article title, summary, and body markdown with ticker, publisher, and date filters
• Derived news-timeline for bounded issuer event timelines across a week or month, with bucketed key events and coverage metadata
• news and news-search expose count, limit, offset, and has_more so agents can page wide historical windows instead of mistaking truncation for a coverage gap
• news and news-search responses include stored body_markdown when article body content is available
• Agent-friendly CLI with clean error output, scoped subcommand help, and self-description via tn-financial-data describe opencli
• Packaged skill bundle for Claude and OpenCode installs
• Typed TypeScript client from the root package export
• Stable production default at https://api.truenorth-financial.ai/v1
• Stored macro endpoints for FRED-backed US rates and economic indicators, plus global central-bank rate history through global-rates, us-rates, and us-economic-indicators

Agent Setup In 60 Seconds

npm install -g tn-financial-data

export TN_FINANCIAL_DATA_API_KEY=<your-api-key>
tn-financial-data query resolve-ticker --query google
tn-financial-data query general-overview --ticker NVDA --period quarterly --financial-limit 4 --news-limit 5
tn-financial-data describe opencli

Live reads accept:

• --api-key <key>
• TN_FINANCIAL_DATA_API_KEY
• TN_FINANCIAL_DATA_API_KEYS

The published CLI reads those values from the current process environment only. Use resolve-ticker to map company or brand input to supported symbols. Treat available-tickers as the authoritative support list for exact symbols; do not silently swap an unsupported exact ticker to a different share class. available-tickers is the equity-symbol snapshot only; covered macro series are queried through global-rates, us-rates, and us-economic-indicators.

What success looks like:

• resolve-ticker returns a supported ticker or an explicit unsupported/ambiguous state
• general-overview returns one company facts block, financials, a price snapshot, and recent news
• describe opencli prints the machine-readable CLI contract that tool-aware runtimes can ingest

Execution best practice after setup:

• treat describe opencli as setup metadata, not a per-task preflight step
• do not start routine reads with tn-financial-data --help, which tn-financial-data, skill print, or skill targets
• once the route is clear, go straight to the narrowest tn-financial-data query ... command
• use the explicit tn-financial-data query <resource> ... form for live reads; do not guess alias verbs
• only use resolve-ticker when the ticker is ambiguous or missing

Production default:

https://api.truenorth-financial.ai/v1

Start Here By Task

| If the prompt is about... | Start with... | Then usually follow with... | | --- | --- | --- | | one company, broad | general-overview | financial-metrics, quarterly-highlights, news | | company name without trusted ticker | resolve-ticker | the narrow read that matches the ask | | a specific statement or ratio | financials or financial-metrics | financial-metrics-snapshot or quarterly-highlights | | latest-quarter product mix or issuer KPIs | quarterly-highlights | earnings, segmented-revenues | | SEC filing discovery or raw filing text | filings | filing-items | | issuer-specific recent news | news | snapshot or general-overview; page with --offset when the user wants the full date-window spectrum | | issuer-specific key news timeline across a period | news-timeline | news only if the user explicitly wants raw article rows too | | keyword, theme, or macro news | news-search | us-rates or us-economic-indicators when the user wants the data too; page with --offset for wide windows | | upcoming earnings | earnings-calendar | earnings or earnings-transcripts | | who owns a stock | institutional-ownership | general-overview | | what a manager holds | investor-portfolio | institutional-ownership only if the user then switches to issuer ownership | | macro rates, CPI, GDP, unemployment | global-rates, us-rates, or us-economic-indicators | news-search for recent headline context | | ETF composition or holdings | etf-profile | etf-holdings | | covered-universe filtering | screen-fields | screen |

Routing rules that matter:

• do not use available-tickers as a macro coverage check
• do not send topic words like CPI, Fed, or tariff to news --ticker
• do not use earnings-transcripts alone for quote or tone questions
• do not pass tickers positionally to query resources that expect --ticker
• do not silently substitute an unsupported exact ticker with another share class
• do not start Apple product-mix prompts with segmented-revenues
• do not infer a news coverage gap from one newest-first page when has_more is true or the returned timestamps cluster near the end of the requested range

Historical News Windows

When the prompt asks for one or two weeks of company news, or for "everything in March," separate timeline synthesis from raw article retrieval.

• use news-timeline first when the user wants the important issuer events across the window

• for month-long key-event summaries, prefer news-timeline --bucket week unless the user explicitly wants daily granularity

• use news or news-search when the user explicitly wants raw article rows, exhaustive coverage checks, or publisher-level inspection

• do not rebuild a month timeline from raw pages when news-timeline fits the ask

• both news surfaces are newest-first inside the filtered date window

• inspect count, limit, offset, and has_more before concluding older dates are absent

• use --sort published_at --order asc when the user wants the raw feed rendered oldest-to-newest as a timeline

• for historical or month-long timeline prompts, start with explicit --start-date and --end-date before any --offset paging

• for bounded historical windows, prefer one bounded call with a sufficiently large --limit first, then page with --offset only if has_more remains true

• the CLI also accepts --from and --to as news-only aliases, but the canonical contract remains --start-date and --end-date

• if returned published_at values cluster near the end of the range, fetch older rows with --offset

• if the user wants the full period, synthesize across multiple pages or split the window into smaller date ranges

• do not widen to earnings, general-overview, or snapshot unless the user asked for that extra context or the news window itself shows a specific event you need to confirm

Examples:

tn-financial-data query news-timeline --ticker NVDA --start-date 2026-03-05 --end-date 2026-04-04
tn-financial-data query news --ticker GOOG --start-date 2026-03-22 --end-date 2026-04-05 --limit 20
tn-financial-data query news --ticker GOOG --start-date 2026-03-22 --end-date 2026-04-05 --limit 20 --offset 20
tn-financial-data query news --ticker GOOG --start-date 2026-03-22 --end-date 2026-03-31 --limit 50

Quick Start

tn-financial-data query resolve-ticker --query google
tn-financial-data query resolve-ticker --query google --query meta --query nvda
tn-financial-data query available-tickers
tn-financial-data query snapshot --tickers AAPL,MSFT,NVDA
tn-financial-data query financial-metrics-snapshot --tickers AAPL,MSFT,NVDA --period annual
tn-financial-data query earnings-transcripts --ticker AAPL --limit 4
tn-financial-data query earnings-calendar --tickers AAPL,MSFT --start-date 2026-04-02 --end-date 2026-04-16
tn-financial-data query dividends --ticker AAPL --limit 10
tn-financial-data query us-rates --series us_treasury_2y,us_treasury_10y,fed_funds_rate --start-date 2021-01-01 --end-date 2026-04-01 --limit 2000
tn-financial-data query us-economic-indicators --series us_cpi,us_unemployment,us_gdp --start-date 2021-01-01 --end-date 2026-04-01 --limit 120
tn-financial-data query company --ticker AAPL
tn-financial-data query news-timeline --ticker NVDA --start-date 2026-03-05 --end-date 2026-04-04
tn-financial-data query news-search --query "tariff semiconductor" --ticker NVDA --limit 10
tn-financial-data query news --ticker GOOG --start-date 2026-03-22 --end-date 2026-04-05 --limit 20 --offset 20
tn-financial-data query filings --ticker AAPL --filing-type 8-K --limit 5
tn-financial-data query general-overview --ticker AAPL --period quarterly --financial-limit 4 --news-limit 5
tn-financial-data skill install --tool claude
tn-financial-data describe opencli

Ownership semantics:

• institutional-ownership is issuer-centric: ticker to holders
• investor-portfolio is investor-centric: filer to holdings via SEC 13F

Macro note:

• us_cpi is the raw CPI index level, not a precomputed inflation transform
• For MoM or YoY CPI prompts, derive the percentage change from adjacent observations returned by us-economic-indicators

Commands

| Command | Description | | --- | --- | | tn-financial-data query ... | Hosted reads over the stable API contract | | tn-financial-data skill install | Install the packaged skill bundle | | tn-financial-data skill print | Print the packaged skill or adapter metadata | | tn-financial-data describe opencli | Emit machine-readable CLI metadata for agents |

Agent Integration

Agents only need one of these setups:

• CLI-native: give the agent shell access plus TN_FINANCIAL_DATA_API_KEY
• Skill-native: install the packaged skill bundle for the agent runtime
• Tool-native: load tn-financial-data describe opencli and let the runtime call query commands directly

Claude and OpenCode install path:

tn-financial-data skill install --tool claude
tn-financial-data skill install --tool opencode

OpenAI-style adapter output:

tn-financial-data skill print --adapter openai

Machine-readable command contract:

tn-financial-data describe opencli

The strongest packaged combination for agents is:

1. packaged skill for routing and prompt steering
2. describe opencli for tool-aware runtimes
3. direct query commands for execution

For end-to-end command compositions, read:

• CLI Reference
• Workflow Recipes

Common query examples:

tn-financial-data query snapshot --tickers AAPL,MSFT,NVDA
tn-financial-data query financial-metrics-snapshot --tickers AAPL,MSFT,NVDA --period annual
tn-financial-data query financials --ticker AAPL --period annual --statement all
tn-financial-data query financial-metrics --ticker AAPL --period annual --limit 4
tn-financial-data query earnings --ticker AAPL --period quarterly --limit 8
tn-financial-data query earnings-transcripts --ticker AAPL --limit 4
tn-financial-data query earnings-calendar --tickers AAPL,MSFT --start-date 2026-04-02 --end-date 2026-04-16
tn-financial-data query quarterly-highlights --ticker AAPL
tn-financial-data query dividends --ticker AAPL --limit 10
tn-financial-data query splits --ticker AAPL --limit 10
tn-financial-data query us-rates --series us_treasury_2y,us_treasury_10y,fed_funds_rate --start-date 2021-01-01 --end-date 2026-04-01 --limit 2000
tn-financial-data query us-economic-indicators --series us_cpi,us_unemployment,us_gdp --start-date 2021-01-01 --end-date 2026-04-01 --limit 120
tn-financial-data query filings --ticker AAPL --filing-type 10-K,10-Q,8-K --limit 10
tn-financial-data query filing-items --ticker AAPL --accession-number 0000320193-26-000005 --item 2.02 --include-exhibits
tn-financial-data query prices --ticker AAPL --interval day --start-date 2025-01-01 --end-date 2025-01-31
tn-financial-data query news --ticker AAPL --limit 10
tn-financial-data query news-timeline --ticker NVDA --start-date 2026-03-05 --end-date 2026-04-04
tn-financial-data query news --ticker GOOG --start-date 2026-03-22 --end-date 2026-04-05 --limit 20 --offset 20
tn-financial-data query news-search --query "AI data center" --publisher Reuters --limit 10
tn-financial-data query institutional-ownership --ticker AAPL --limit 20
tn-financial-data query investor-portfolio --investor vanguard --limit 20
tn-financial-data query global-rates --series ecb_refi,boe_sonia --limit 10
tn-financial-data query etf-profile --ticker SPY
tn-financial-data query etf-holdings --ticker SPY --limit 20
tn-financial-data query screen --filter "trailing_pe < 25" --filter "recommendation_key = buy" --limit 10

Example agent prompts after install:

Use tn-financial-data to summarize NVDA's latest quarter.
Use tn-financial-data to find Apple's latest 8-K and extract Item 2.02 plus exhibits.
Use tn-financial-data to compare US 10-year yields, Fed funds, and CPI over the last 24 months.
Use tn-financial-data to search recent news on CPI, Fed, and tariffs, then summarize the dominant themes.

Installing the skill bundle does not provision API access. The agent process itself still needs TN_FINANCIAL_DATA_API_KEY or TN_FINANCIAL_DATA_API_KEYS in its runtime environment.

Rate Limits

The hosted API returns standard rate-limit headers:

• X-RateLimit-Limit
• X-RateLimit-Remaining
• X-RateLimit-Reset
• Retry-After on 429

When the CLI is throttled, it prints a clean retry message instead of a stack trace.

Minimum Contract

The minimum direct contract is:

tn-financial-data describe opencli
tn-financial-data query <resource> [options]

TypeScript Client

import { TnFinancialData } from "tn-financial-data";

const client = new TnFinancialData({
  apiKey: process.env.TN_FINANCIAL_DATA_API_KEY!,
});

const resolution = await client.resolveTicker("google");
console.log(resolution.status, resolution.resolved_ticker);

const batchResolution = await client.resolveTickers(["google", "meta", "nvda"]);
console.log(batchResolution.results.map((row) => `${row.query}:${row.status}`));

const calendar = await client.getEarningsCalendar({
  tickers: ["NVDA", "KO"],
  startDate: "2026-04-01",
  endDate: "2026-06-30",
});

console.log(calendar.events.map((row) => `${row.ticker}:${row.event_date_start}`));

const transcripts = await client.getEarningsTranscripts("NVDA", {
  limit: 1,
});

console.log(
  transcripts.transcript_coverage.status,
  transcripts.transcripts[0]?.quarter_label,
  transcripts.transcripts[0]?.question_count,
);

const usRates = await client.getUsInterestRates({
  series: ["us_treasury_10y", "fed_funds_rate"],
  startDate: "2021-01-01",
  endDate: "2026-04-01",
  limit: 2000,
});

console.log(usRates.rates.map((row) => `${row.key}:${row.latest?.value}`));

const filings = await client.getFilings("AAPL", {
  filingTypes: ["8-K"],
  limit: 3,
});

console.log(filings.filings[0]?.accession_number);

const news = await client.searchNews("AI data center", {
  ticker: "NVDA",
  publisher: "Reuters",
  limit: 5,
});

console.log(news.news[0]?.title, news.count);

const filingItems = await client.getFilingItems("AAPL", {
  accessionNumber: "0000320193-26-000005",
  filingType: "8-K",
  items: ["2.02"],
  includeExhibits: true,
});

console.log(filingItems.filing_document.exhibits?.[0]?.number);
console.log(filingItems._rateLimit);

const etfProfile = await client.getEtfProfile("SPY");
console.log(etfProfile.profile?.name, etfProfile.profile?.beta);

const etfHoldings = await client.getEtfHoldings("SPY", { limit: 10 });
console.log(etfHoldings.holdings.map((h) => `${h.asset_symbol}:${h.weight_percentage}%`));

Package Scope

The published npm package is intentionally limited to agent-facing surfaces. Repository-specific website, local playground, and self-hosting workflows live in the GitHub repository, not in the npm contract.