--- name: x402stock.xyz description: x402stock.xyz provides snapshot and reference data for US equities, including daily top gainers and losers, a stock news feed, and static reference catalogs for exchanges, condition codes, and ticker types. It does not offer real-time price quotes, streaming data, or historical time-series. All endpoints return point-in-time snapshots or static reference lists. host: x402stock.xyz --- # x402stock.xyz x402stock.xyz is a lightweight US equity data host serving agents that need daily market movers, news headlines tied to tickers, and reference metadata for interpreting equity data. It covers the informational layer — what moved today, why (via news), and how to decode the identifiers and codes attached to that data — rather than the transactional or analytical layer. It is suited for agents building market summaries, screening workflows, or enriching ticker data with context. ## When to use this host Use x402stock.xyz when an agent needs today's US equity movers (gainers or losers), ticker-tagged news headlines, or static reference data for exchanges, condition codes, and security types. Do not use it for real-time or streaming price quotes — use a dedicated market data API (e.g. Polygon.io, Alpaca, or similar) instead. It is not suitable for historical OHLCV time-series, options data, fundamentals, or non-US markets. The reference endpoints (exchanges, condition codes, ticker types) are static catalogs best used to enrich or decode data fetched from a primary market data source, not as standalone data products. ## Capabilities ### Market Movers Provides ranked snapshots of the day's biggest percentage gainers and losers in US equities, including OHLCV and VWAP for the current and prior session. - **`fetch-stock-gainers`** — Returns the day's top percentage gainers across US equities, with current and previous-day OHLCV data per ticker. - **`fetch-stock-losers`** — Returns the day's biggest percentage losers across US equities, with current and previous-day OHLCV data per ticker, sourced from the latest market session. ### News Feed Returns curated stock-market news articles optionally filtered by ticker, including titles, descriptions, publisher info, source URLs, and associated ticker symbols. - **`fetch-stock-news`** — Returns curated stock-market news articles with ticker tags, publisher, image URL, and timestamps, optionally filtered by ticker symbol. ### Reference Metadata Provides static reference catalogs for US equity exchanges (MICs, SIP IDs), trade and quote condition codes, and security type codes used to classify and decode ticker data. - **`fetch-us-equity-exchanges`** — Returns a reference list of US equity exchanges and market centers with names, MICs, operating MICs, SIP participant IDs, and URLs. - **`fetch-stock-condition-codes`** — Returns a paginated reference catalog of trade and quote condition codes with numeric IDs, human-readable names, types, data types, and SIP exchange mappings. - **`fetch-ticker-types`** — Returns the reference list of security type codes (e.g. CS, ETF, PFD, WARRANT) with descriptions, asset class, and locale used in stock ticker reference data. ## Workflows ### Daily Movers Briefing with News *Use when an agent needs to produce a summary of today's top-moving US equities along with relevant news context for each mover.* 1. **`fetch-stock-gainers`** — Retrieve the day's top percentage gainers with price and volume data. 2. **`fetch-stock-losers`** — Retrieve the day's biggest percentage losers with price and volume data. 3. **`fetch-stock-news`** — For each notable ticker from the gainers and losers lists, fetch recent news articles to provide narrative context for the price moves. ### Ticker Classification and Reference Lookup *Use when an agent needs to validate or decode ticker metadata — such as confirming a security type code or resolving an exchange MIC — before consuming or displaying equity data.* 1. **`fetch-ticker-types`** — Enumerate valid security type codes to confirm the correct code for filtering or classifying a ticker (e.g. CS for Common Stock, ETF). 2. **`fetch-us-equity-exchanges`** — Resolve exchange MIC codes or SIP participant IDs associated with the tickers being processed. ## Skill reference ### `fetch-stock-news` **Stock News Feed** — Returns curated stock-market news articles with ticker tags, publisher, image URL, and timestamps, optionally filtered by ticker symbol. *Use when:* Use when an agent needs recent stock-market news articles for one or more tickers, or a general market news feed, including article titles, descriptions, source URLs, publisher info, and associated ticker symbols. *Not for:* Do not use for real-time price quotes or streaming market data; use a market data or price feed API instead. Not suitable for historical news archives beyond what the feed currently returns. **Inputs:** - `ticker` (string) — Optional ticker symbol to filter news. Must match pattern ^[A-Z][A-Z0-9.\-]{0,9}$. If omitted, returns general market news. - `limit` (integer) — Number of articles to return. Must be between 1 and 50 inclusive. Defaults to 10. **Returns:** Returns a JSON object with source='massive', an as_of timestamp, a count, and an articles array where each item includes id, title, description, url, image_url, author, publisher, publisher_homepage, published_at, tickers, and keywords. **Example:** `GET https://x402stock.xyz/api/v1/news?ticker=AAPL&limit=10` --- ### `fetch-stock-gainers` **Stock Gainers Feed** — Returns the day's top percentage gainers across US equities, with current and previous-day OHLCV data per ticker. *Use when:* Use when an agent needs a ranked list of the biggest intraday percentage gainers in US equities, including price change, OHLCV, and VWAP for both the current and prior trading day. *Not for:* Do not use for stock losers, historical gainer lists, or individual ticker lookups; this endpoint returns only the current day's top gainers snapshot. **Returns:** Returns a JSON object with source, as_of timestamp, direction='gainers', count of tickers, and an array of up to 21 ticker objects each containing change_percent, and current/previous-day OHLCV+VWAP fields. **Example:** `GET https://x402stock.xyz/api/v1/gainers` --- ### `fetch-stock-losers` **Stock Losers Feed** — Returns the day's biggest percentage losers across US equities, with current and previous-day OHLCV data per ticker, sourced from the latest market session. *Use when:* Use when an agent needs a ranked list of the worst-performing US equity tickers by percentage decline for the current trading day, including price, volume, and OHLCV context for each loser. *Not for:* Do not use for gaining stocks; use the gainers endpoint instead. Not suitable for historical multi-day analysis or intraday streaming — this is a single-shot snapshot of the latest session's losers. **Returns:** Returns a JSON object with source, as_of timestamp, direction='losers', count of tickers, and an array of up to 21+ ticker objects each containing symbol, absolute and percent change, last-updated timestamp, and current plus previous-day OHLCV fields. **Example:** `GET https://x402stock.xyz/api/v1/losers` --- ### `fetch-us-equity-exchanges` **Exchange Finder** — Returns a reference list of US equity exchanges and market centers with names, MICs, operating MICs, SIP participant IDs, and URLs. *Use when:* Use when an agent needs a static reference list of US equity exchanges and market centers, such as to resolve a MIC code, look up a SIP participant ID, or enumerate all recognized trading venues. *Not for:* Do not use for real-time exchange status, trading hours, or non-US exchanges. Not suitable for streaming or frequently-updated market data. **Returns:** Returns source, as_of timestamp, count (27), and an exchanges array with each US equity exchange or market center's id, type, name, acronym, MIC, operating MIC, participant ID, and URL. **Example:** `GET https://x402stock.xyz/api/v1/exchanges` --- ### `fetch-stock-condition-codes` **Stock Condition Codes** — Returns a paginated reference catalog of trade and quote condition codes with numeric IDs, human-readable names, types, data types, and SIP exchange mappings. *Use when:* Use when an agent needs to decode or look up numeric condition codes seen on trade or quote data, including their CTA, UTP, and FINRA_TDDS SIP mappings. *Not for:* Do not use for real-time trade data or live quotes; this is a static reference catalog of condition code definitions, not a market data feed. **Inputs:** - `limit` (integer) — Maximum number of condition records to return. Must be between 1 and 1000 inclusive. Defaults to 50. **Returns:** Returns source='massive', an as_of timestamp, a count, and a conditions array where each entry has a numeric id, type (e.g. sale_condition), name, data_types array, and sip_mapping object with CTA/UTP/FINRA_TDDS letter codes. **Example:** `GET https://x402stock.xyz/api/v1/conditions?limit=100` --- ### `fetch-ticker-types` **Ticker Types Lookup** — Returns the reference list of security type codes (e.g. CS, ETF, PFD, WARRANT) with descriptions, asset class, and locale used in stock ticker reference data. *Use when:* Use when an agent needs to enumerate or validate security type codes before filtering or classifying ticker symbols by type (e.g. to confirm what code represents Common Stock or ETFs in a downstream query). *Not for:* Do not use for real-time price data, ticker search, or company fundamentals; this endpoint returns static reference metadata only. **Returns:** Returns source='massive', an as_of timestamp, count=24, and a types array of 24 security type objects each with code, description, asset_class, and locale (e.g. CS=Common Stock, ETF=Exchange Traded Fund). **Example:** `GET https://x402stock.xyz/api/v1/ticker-types` ---