tn-financial-data

Hosted US equity, ETF, FX, commodity, market news, macro, SEC filing, and earnings transcript coverage for agents — 300 US stocks, 61 ETFs, 30 FX pairs, 12 commodities, and stored macro series.

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

• tn-financial-data query ...
• tn-financial-data ask-agent "<question>" — ask the hosted TrueNorth agent
• 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 overview (profile + holdings + price + news in one call), prices, canonical issuer news, insider trades, ownership, earnings transcript structure and coverage, stored macro history, raw SEC filings, fixed-registry FX reads, and fixed-registry commodity reads 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
• FX surfaces through fx-pairs, fx-snapshot, and fx-rates, with a fixed 30-pair registry and daily historical storage
• Commodity surfaces through commodities, commodity-snapshot, and commodity-prices, with a fixed 12-commodity registry and daily historical storage
• Canonical issuer-scoped news plus scoped news-search over article title, summary, and body markdown with ticker, publisher, date, scope, and repeated market topic filters
• news-search --scope market for broad market, macro, rates, policy, economy, and geopolitical retrieval through the market-news enrichment pipeline
• Hosted ask-agent broad-market prompts are grounded in live news-search --scope market, rates, macro, and snapshot reads rather than bundled canned market text
• 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

Coverage

| Modality | Count | Depth | |----------|-------|-------| | US stocks | 300 | prices, financials, earnings, insider trades, transcripts, news | | US ETFs | 61 | price snapshots, holdings, profile, bundled overview | | FX pairs (curated registry) | 30 | latest snapshot plus 5 years of daily history | | Commodities (curated registry) | 12 | latest snapshot plus 5 years of daily history | | Market news | hosted corpus | market, macro, rates, policy, economy, geopolitical | | Macro series | fixed stored set | US rates, US CPI/GDP/unemployment, global policy rates |

Data surfaces per stock ticker: daily OHLCV prices, quarterly SEC EDGAR financials (income statement, balance sheet, cash flow), earnings estimates and actuals, insider trades (Form 4), earnings call transcripts, and issuer news from multiple providers.

Use tn-financial-data query available-tickers for the live supported symbol list.

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 query etf-overview --ticker SPY --holdings-limit 25 --news-limit 5
tn-financial-data query fx-snapshot --pairs eurusd,usdjpy
tn-financial-data query commodity-snapshot --commodities gold,wti,brent
tn-financial-data query news-search --query "stock market" --scope market --start-date 2026-04-03 --end-date 2026-04-10 --limit 10
tn-financial-data ask-agent "what's up with the market this week?"
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; use fx-pairs for the supported FX registry, and query covered macro series 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
• fx-snapshot returns the latest quote state for supported FX pairs
• commodity-snapshot returns the latest quote state for supported commodities
• news-search --scope market returns curated market-news rows with topics, tags, asset_labels, and analysis_markdown
• 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 --scope market for broad market, macro, or geopolitical prompts | us-rates or us-economic-indicators when the user wants the data too; page with --offset for wide windows | | supported FX pairs or FX coverage | fx-pairs | fx-snapshot or fx-rates | | latest FX level or short pair check | fx-snapshot | fx-rates if the user wants trend or regime context | | historical FX series | fx-rates | news-search --scope market for macro context | | supported commodities or commodity coverage | commodities | commodity-snapshot or commodity-prices | | latest commodity level or short commodity check | commodity-snapshot | commodity-prices if the user wants trend or regime context | | historical commodity series | commodity-prices | news-search --scope market for macro context | | 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 use available-tickers as an FX coverage check
• do not use available-tickers as a commodity coverage check
• do not send topic words like CPI, Fed, or tariff to news --ticker
• do not route FX pairs into resolve-ticker, general-overview, or stock snapshot
• do not route commodities into resolve-ticker, general-overview, stock snapshot, or FX reads
• for prompts like "what's up with the market?", "market today", or "what geopolitical news is moving stocks?", start with news-search --scope market
• 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 fx-pairs
tn-financial-data query fx-snapshot --pairs eurusd,usdjpy,gbpusd
tn-financial-data query fx-rates --pairs eurusd,usdjpy --start-date 2026-01-01 --end-date 2026-04-10 --limit 90
tn-financial-data query commodities
tn-financial-data query commodity-snapshot --commodities gold,wti,brent
tn-financial-data query commodity-prices --commodities gold,wti --start-date 2026-01-01 --end-date 2026-04-10 --limit 90
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 news-search --query "stock market" --scope market --start-date 2026-04-03 --end-date 2026-04-10 --limit 20
tn-financial-data query news-search --query "Federal Reserve" --scope market --topic rates --start-date 2026-04-03 --end-date 2026-04-10 --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 "stock market" --scope market --start-date 2026-04-03 --end-date 2026-04-10 --limit 20
tn-financial-data query news-search --query "tariff semiconductor" --scope market --topic policy --topic economy --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
• FX phase 1 is daily history plus latest snapshot state; do not imply intraday FX support
• commodity phase 1 is daily history plus latest snapshot state; do not imply intraday commodity support

Commands

| Command | Description | | --- | --- | | tn-financial-data query ... | Hosted reads over the stable API contract | | tn-financial-data ask-agent "<question>" | Ask the hosted TrueNorth agent a question | | 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

Asking the TrueNorth agent

ask-agent is for human CLI users and external integrations that want to delegate natural-language questions to the hosted TrueNorth research agent and get a synthesized answer back. Use it when:

• You're at a terminal and want a quick answer without writing query commands
• You're building a script, chatbot, or backend service that wants to embed a financial-domain agent without building one yourself
• You want the same response your browser would get from the hosted playground UI, but without a browser

If you're building an AI agent that needs raw financial data and will do its own analysis (e.g., installing this package as a tool for Claude, OpenCode, or your own Python/TypeScript runtime), install the skill bundle and use the query commands directly (tn-financial-data skill install --tool claude). The query commands are faster, cheaper, and give your agent full control over analysis and synthesis. The hosted TrueNorth agent itself uses those same query commands under the hood, so calling ask-agent from inside another agent is circular and adds latency for no benefit.

Use ask-agent to ask the hosted TrueNorth agent a question from the command line. The response is the same reply the web playground sees.

# Plain text to your terminal (live stream)
tn-financial-data ask-agent "What are Nvidia's recent tailwinds?"

# Markdown rendering: bold, italic, headers, lists, and pipe tables get
# rendered as ANSI styling + Unicode box-drawn tables. Tool calls keep
# streaming live; the prose response is buffered and rendered at end.
tn-financial-data ask-agent "NVDA Q4 earnings beat" --markdown

# Pipe-friendly plain text
tn-financial-data ask-agent "Explain Tesla Q3" | less

# Full JSON payload for scripting
tn-financial-data ask-agent "..." --json | jq -r '.response'

# Raw NDJSON stream (useful for audit logs)
tn-financial-data ask-agent "..." --stream > events.ndjson

When the agent uses tools (like the built-in bash runner), the CLI shows the tool name and the actual command on a continuation line, e.g.:

→ bash: Get NVDA current price snapshot
  ↳ tn-financial-data query snapshot --ticker NVDA

ask-agent uses the same API key as query: pass --api-key, set TN_FINANCIAL_DATA_API_KEY, or put it in TN_FINANCIAL_DATA_API_KEYS.

To target a non-default playground host (for example a staging deployment or a local dev server), pass --base-url or set TN_FINANCIAL_DATA_PLAYGROUND_BASE_URL. The default is https://truenorth-financial.ai.

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.