/deepxiv-fa-stocks

name: deepxiv-fa-stocks
description: Point-in-time US equity data for 8,000+ tickers: daily prices vs sector and SPY, per-ticker news and event clusters, SEC filings, XBRL financials, macro series and the daily macro digest, all replayable with as_of. Use for questions about a US stock, a market theme, or US macro data.

DeepXiv · 美股数据 (`stocks`)

NASDAQ point-in-time US equity data. US equities: prices, news, SEC filings, insider trades, financials, macro series and events, all with as_of point-in-time replay (only data visible at that moment).

Setup

pip install -U deepxiv-sdk      # deepxiv registers a token on first use

With a registered key (https://data.rag.ac.cn/register), `search` and `read` are fair use: 60/min, 5 at once, 5,000/day; on the auto-registered token they spend the deepxiv daily limit at the credits listed below. `ask` draws on the daily ask allowance (resets 00:00 UTC; a site-wide daily total can run out early at peak times), or 3 lifetime trial asks on the auto-registered token. On 429, back off for `Retry-After` seconds. Data goes to stdout; cost, quota and sources go to stderr. Exit 0 ok, 1 API error, 2 usage error. The general CLI guide is the `deepxiv-cli` skill.

Start here

deepxiv fa read stocks NVDA   # price vs sector ETF and SPY, recent events, news, filings
deepxiv fa read stocks NVDA -e news   # the ticker's news feed
deepxiv fa read stocks NVDA -e financials   # XBRL financials, as filed
deepxiv fa read stocks NVDA -p as_of=2026-09-04   # the same view as of a past day
deepxiv fa search stocks "AI data center power" -F source=stocks   # which tickers a theme touches
deepxiv fa search stocks "chip export restrictions" -k 5   # news + events + filings, ranked together
deepxiv fa search stocks "earnings guidance" -F ticker=TSLA -F source=events
deepxiv fa read stocks digest:macro   # today's macro releases, rates, FX, commodities
deepxiv fa read stocks macro:CPIAUCSL   # a macro series with vintages and nowcast
deepxiv fa ask "CoreWeave 最近一周为什么大跌？结合价格、新闻和财报说明" -d stocks   # cited analysis

Free samples: ids `AAPL`, `NVDA`, `macro:CPIAUCSL`; queries `chip export restrictions`, `cloud server`.

Search

deepxiv fa search stocks "query" [-F FILTER]... [-k N] [--offset N] [--mode M] [--head] [--json]

Modes: keyword. Up to 100 hits. Cost 2 (with `--head`: 3). An empty query is rejected; use `"*"` to list by filters only. Filters combine with AND; an undeclared field exits 2.

| filter | type | `-F` syntax | meaning | |---|---|---|---| | `source` | keyword | `k=v` | What to search: all (default; news + events + filings ranked together, and the first page also returns `stocks`: the top 5 matching tickers) \| news \| events \| filings \| stocks (find stocks by theme / business) \| insiders (time-ordered only) Values: `all`, `news`, `events`, `filings`, `stocks`, `insiders`. | | `ticker` | keyword | `k=v` | Ticker symbol | | `as_of` | keyword | `k=v` | Point in time (ISO date or datetime), passed through unchanged | | `date` | datetime | `k>=n`, `k=n..m` | Time range {gte, lte} → upstream from / to |

Advanced filters (see `deepxiv fa spec stocks`): `news_kind`, `form`, `event_type`, `semantic`, `with_returns`, `side`, `min_value`.

Read

deepxiv fa read stocks ID [ID...] [-l brief|detail|full] [-e EXTRA] [-p k=v]... [-f json|md|html]

| level | credits | returns | |---|---|---| | `brief` | 1 | Ticker overview: latest price, recent events, news, filings | | `detail` (default) | 1 | Ticker overview: latest price, recent events, news, filings | | `full` | 2 | Ticker digest input (every item carries a citable id; built on demand, ~45 s) |

| `-e` extra | credits | returns | |---|---|---| | `prices` | 1 | Prices: interval=1d \| 1m (IEX minute bars) | | `financials` | 1 | Financials (XBRL, as filed; later restatements hidden) | | `events` | 1 | Events (merged from news / 8-K / Form 4) | | `news` | 1 | News | | `filings` | 1 | SEC filings | | `insiders` | 1 | Insider open-market trades (Form 4 P/S) | | `features` | 2 | Features (price / event derived) |

At `-l full`, `-p section=NAME` reads one section and `-p characters=N` the first N characters.

Facets

`deepxiv fa facets stocks FIELD` lists the legal values and counts, free. Use it instead of guessing a spelling. Fields: `source`, `news_kind`, `form`, `event_type`, `semantic`, `side`.

Ask

deepxiv fa ask "question" -d stocks [-e low|medium|high] [-p k=v]... [--no-stream] [--json]

Ask about US equities: companies by theme, a ticker's prices and news flow, events, insider trades, financials, macro; questions about a past moment are answered as_of that moment. Citations are upstream record ids ([stocks:<id> title]); answers end with data sources and a not-investment-advice note

Always pass `-d stocks`: automatic domain picking is still early.

What this corpus will and will not tell you

• read 的 id：代码（AAPL）、macro:<series>（如 macro:CPIAUCSL）、digest:market、digest:macro，或任一条记录的 id（news:… / evt_… / filing:…）
• search：文字按相关性（filters.source = all \| news \| events \| filings），source=stocks 按主题找股票；query 为 '*' 或全大写代码时按时间倒序列出（insiders 只能这样）
• as_of：search 放 filters.as_of，read 用查询参数 as_of；不带 = 现在。结果缓存 60 秒
• 每条记录带 license（取值和说明见下面的 license · 各行）
• as_of 口径 · prices: daily bar of D visible after D 16:00 ET; 1m IEX bar visible at ts+1min
• as_of 口径 · news: visible_at (live: first_seen_at; backfilled: crawl_at + 336 s)
• as_of 口径 · filings: live 8-K / Form 4: acceptance (or first_seen_at if later); date-only filings: 22:00 ET of the date
• as_of 口径 · financials: XBRL facts with filed date <= as_of (filed date counts from 22:00 ET)
• as_of 口径 · macro: ALFRED vintage at as_of; daily FRED series: value dated X visible from X+1 17:00 ET; Treasury curve from 18:00 ET (backfill) / first seen (live); monthly releases after 16:00 ET on release day for the daily cut
• as_of 口径 · events: cluster/member first_seen_at; partial clusters re-derive di