# x402stock — market & economic data for AI agents

> A pay-per-request HTTP API that resells real-time US stock data and a broad catalog of market, on-chain, and economic data to AI agents. No API keys or accounts — callers pay in USDC per request via the x402 + MPP standards.

## What this is

x402stock is an HTTP API built for autonomous agents. There is no signup, no API key, and no account: an agent calls an endpoint, gets an HTTP 402 with payment requirements, pays a few cents of USDC, and retries to receive JSON. Every response is shaped `{ ticker, data, source, as_of }`.

It exposes 114 paid endpoints plus free market-status endpoints, spanning US equities, ETFs & options, forex, centralized and on-chain crypto (Hyperliquid perps & spot, Solana), energy commodities, US and global macro (Fed funds, CPI/PCE, jobs, GDP, Treasury debt & yields, World Bank), SEC EDGAR filings, congressional trades, government spending, and market sentiment.

## How payment works

1. Call any paid endpoint with no payment → the server replies `HTTP 402 Payment Required` with an x402/MPP challenge describing price, network, and payee.
2. Pay the quoted USDC amount with an x402 or MPP client (e.g. `@agentcash/router`, the AgentCash MCP, or any x402-compatible wallet). Settlement is on Base by default (Solana/Tempo where enabled); on Base via Coinbase CDP the buyer pays no gas.
3. Retry the same request with the payment proof → `HTTP 200` with the JSON payload.

Free endpoints (market status, market holidays) return `HTTP 200` directly with no payment.

## Pricing

Prices are per request, in USD and settled as USDC. The ladder: **$0.01** base (single upstream call / reference data), **$0.02** mid (multi-item parses, fundamentals, movers), **$0.03** heavy (composite indicators, AI summaries), **$0.04** bulk (whole-market snapshot), **$0.05** top (overview, compare, macro bundle).

## Stock prices & snapshots

- [GET /api/v1/overview/{ticker}](https://x402stock.xyz/api/v1/overview/AAPL): $0.05 — Everything about one stock in one call: profile, price, fundamentals, technicals, news, peers
- [GET /api/v1/compare](https://x402stock.xyz/api/v1/compare): $0.05 — Compare 2 to 3 stocks side by side: price, P/E, market cap, margins, yield
- [GET /api/v1/quote/{ticker}](https://x402stock.xyz/api/v1/quote/AAPL): $0.01 — Last price for a US stock, 15 minute delayed
- [GET /api/v1/snapshot/{ticker}](https://x402stock.xyz/api/v1/snapshot/AAPL): $0.01 — Full ticker snapshot (last quote, last trade, OHLC, prev close, %change)
- [GET /api/v1/aggregates/{ticker}](https://x402stock.xyz/api/v1/aggregates/AAPL): $0.02 — Historical price history: OHLC bars over any timespan and date range
- [GET /api/v1/prev-close/{ticker}](https://x402stock.xyz/api/v1/prev-close/AAPL): $0.01 — Previous trading day OHLC bar
- [GET /api/v1/open-close/{ticker}](https://x402stock.xyz/api/v1/open-close/AAPL): $0.01 — Daily open/close (+ pre/after-hours) for a specific date
- [GET /api/v1/unified-snapshot](https://x402stock.xyz/api/v1/unified-snapshot): $0.02 — Multi-ticker snapshot: fetch a whole watchlist's prices in one call
- [GET /api/v1/full-market-snapshot](https://x402stock.xyz/api/v1/full-market-snapshot): $0.04 — Whole-market snapshot: every US ticker's current price and day change in one call
- [GET /api/v1/grouped-daily](https://x402stock.xyz/api/v1/grouped-daily): $0.02 — Whole-market daily OHLC for one date

## Movers & screening

- [GET /api/v1/market-pulse](https://x402stock.xyz/api/v1/market-pulse): $0.03 — Market movers in one call: top gainers, top losers, market status, news
- [GET /api/v1/gainers](https://x402stock.xyz/api/v1/gainers): $0.02 — Top gaining US stocks today
- [GET /api/v1/losers](https://x402stock.xyz/api/v1/losers): $0.02 — Top losing US stocks today
- [GET /api/v1/screener](https://x402stock.xyz/api/v1/screener): $0.03 — Screen the whole US market: filter every ticker by price, percent move, and volume in one call

## Technical indicators

- [GET /api/v1/technicals/{ticker}](https://x402stock.xyz/api/v1/technicals/AAPL): $0.03 — Technical indicators in one call: RSI, SMA, EMA, MACD with signal zones
- [GET /api/v1/indicators/sma/{ticker}](https://x402stock.xyz/api/v1/indicators/sma/AAPL): $0.01 — Simple Moving Average (SMA)
- [GET /api/v1/indicators/ema/{ticker}](https://x402stock.xyz/api/v1/indicators/ema/AAPL): $0.01 — Exponential Moving Average (EMA)
- [GET /api/v1/indicators/rsi/{ticker}](https://x402stock.xyz/api/v1/indicators/rsi/AAPL): $0.01 — Relative Strength Index (RSI)
- [GET /api/v1/indicators/macd/{ticker}](https://x402stock.xyz/api/v1/indicators/macd/AAPL): $0.01 — Moving Average Convergence/Divergence (MACD)

## Reference & fundamentals

- [GET /api/v1/ticker/{ticker}](https://x402stock.xyz/api/v1/ticker/AAPL): $0.01 — Company / ticker reference data
- [GET /api/v1/tickers](https://x402stock.xyz/api/v1/tickers): $0.01 — Search / list tickers across stocks, crypto, forex, and indices
- [GET /api/v1/financials/{ticker}](https://x402stock.xyz/api/v1/financials/AAPL): $0.02 — Fundamentals: income, balance sheet, and cash flow statements
- [GET /api/v1/dividends/{ticker}](https://x402stock.xyz/api/v1/dividends/AAPL): $0.01 — Dividend history (cash amount, ex-date, pay date, frequency)
- [GET /api/v1/splits/{ticker}](https://x402stock.xyz/api/v1/splits/AAPL): $0.01 — Stock split history
- [GET /api/v1/splits-calendar](https://x402stock.xyz/api/v1/splits-calendar): $0.02 — Split calendar: upcoming and recent forward & reverse splits across all US tickers
- [GET /api/v1/events/{ticker}](https://x402stock.xyz/api/v1/events/AAPL): $0.01 — Corporate events (ticker changes and more)
- [GET /api/v1/related/{ticker}](https://x402stock.xyz/api/v1/related/AAPL): $0.01 — Related peer companies
- [GET /api/v1/exchanges](https://x402stock.xyz/api/v1/exchanges): $0.01 — US stock exchanges & market centers reference
- [GET /api/v1/conditions](https://x402stock.xyz/api/v1/conditions): $0.01 — Trade & quote condition codes reference
- [GET /api/v1/ticker-types](https://x402stock.xyz/api/v1/ticker-types): $0.01 — Ticker type codes reference (CS, ETF, ADRC, …)

## Options

- [GET /api/v1/options/{ticker}](https://x402stock.xyz/api/v1/options/AAPL): $0.02 — Options chain for a US stock: every contract with strike, expiration, and call/put type
- [GET /api/v1/options-aggregates/{contract}](https://x402stock.xyz/api/v1/options-aggregates/O:AAPL260620C00150000): $0.02 — Historical OHLC bars for a single option contract

## Short interest & squeeze signals

- [GET /api/v1/short-interest/{ticker}](https://x402stock.xyz/api/v1/short-interest/AAPL): $0.02 — Bi-weekly short interest and days-to-cover for a stock
- [GET /api/v1/short-volume/{ticker}](https://x402stock.xyz/api/v1/short-volume/AAPL): $0.02 — Daily short-sale volume and short-volume ratio for a stock
- [GET /api/v1/fails-to-deliver/{ticker}](https://x402stock.xyz/api/v1/fails-to-deliver/AAPL): $0.02 — Fails-to-deliver history for a stock: settlement-fail share volume by date
- [GET /api/v1/squeeze/{ticker}](https://x402stock.xyz/api/v1/squeeze/AAPL): $0.04 — Short-squeeze bundle: short interest, daily short volume, and fails-to-deliver in one call

## SEC filings (EDGAR)

- [GET /api/v1/filings/{ticker}](https://x402stock.xyz/api/v1/filings/AAPL): $0.01 — SEC filing history for a company: 10-K, 10-Q, 8-K, Form 4, and more
- [GET /api/v1/insider-trades/{ticker}](https://x402stock.xyz/api/v1/insider-trades/AAPL): $0.03 — Insider transactions from SEC Form 4: who bought or sold, how much, at what price
- [GET /api/v1/material-events/{ticker}](https://x402stock.xyz/api/v1/material-events/AAPL): $0.03 — Material corporate events from 8-K filings, classified by SEC item code
- [GET /api/v1/concept/{ticker}](https://x402stock.xyz/api/v1/concept/AAPL): $0.02 — Time series of a single XBRL financial fact straight from SEC filings
- [GET /api/v1/company-facts/{ticker}](https://x402stock.xyz/api/v1/company-facts/AAPL): $0.02 — Every reported financial fact for a company, latest value each, straight from SEC XBRL
- [GET /api/v1/filing-summary/{ticker}](https://x402stock.xyz/api/v1/filing-summary/AAPL): $0.03 — AI-structured summary of a 10-K, 10-Q, or 8-K: overview, risk factors, MD&A, guidance
- [GET /api/v1/filing-search](https://x402stock.xyz/api/v1/filing-search): $0.02 — Full-text search across all SEC filings since 2001 by keyword, form type, and date
- [GET /api/v1/frames](https://x402stock.xyz/api/v1/frames): $0.02 — Compare one financial metric across every public company for a single period
- [GET /api/v1/form-3/{ticker}](https://x402stock.xyz/api/v1/form-3/AAPL): $0.02 — Initial insider ownership from SEC Form 3: holdings reported when an insider role begins
- [GET /api/v1/beneficial-ownership/{ticker}](https://x402stock.xyz/api/v1/beneficial-ownership/AAPL): $0.02 — Schedule 13D/13G beneficial-ownership & activist stakes filed on a company (5%+ trigger)
- [GET /api/v1/form-144/{ticker}](https://x402stock.xyz/api/v1/form-144/AAPL): $0.02 — Insider intent-to-sell notices (SEC Form 144) for a company — leads the Form 4
- [GET /api/v1/form-144](https://x402stock.xyz/api/v1/form-144): $0.02 — Market-wide recent insider intent-to-sell notices (SEC Form 144) across all issuers
- [GET /api/v1/fund-holdings/{cik}](https://x402stock.xyz/api/v1/fund-holdings/0001067983): $0.03 — Institutional 13F holdings for a fund by CIK: every position, value, and shares
- [GET /api/v1/fund-nport/{fund}](https://x402stock.xyz/api/v1/fund-nport/SPY): $0.03 — What's inside an ETF or fund: full N-PORT portfolio holdings
- [GET /api/v1/dossier/{ticker}](https://x402stock.xyz/api/v1/dossier/AAPL): $0.05 — SEC filing dossier in one call: recent filings, insider trades, material 8-K events, and Form 3

## IPOs & calendars

- [GET /api/v1/ipos](https://x402stock.xyz/api/v1/ipos): $0.02 — IPO calendar: upcoming and historical US listings with price range and size
- [GET /api/v1/calendar](https://x402stock.xyz/api/v1/calendar): $0.02 — Upcoming US economic data releases + next FOMC meeting
- [GET /api/v1/calendar/fomc](https://x402stock.xyz/api/v1/calendar/fomc): $0.01 — FOMC meeting schedule with last & next meeting and days-until

## Forex & crypto spot

- [GET /api/v1/forex/{pair}/aggregates](https://x402stock.xyz/api/v1/forex/EUR-USD/aggregates): $0.02 — Forex price history: OHLC bars for a currency pair over any timespan and date range
- [GET /api/v1/forex/{pair}/prev-close](https://x402stock.xyz/api/v1/forex/EUR-USD/prev-close): $0.01 — Previous day OHLC bar for a currency pair
- [GET /api/v1/crypto/{pair}/aggregates](https://x402stock.xyz/api/v1/crypto/BTC-USD/aggregates): $0.02 — Crypto price history: OHLC bars for a spot pair over any timespan and date range
- [GET /api/v1/crypto/{pair}/prev-close](https://x402stock.xyz/api/v1/crypto/BTC-USD/prev-close): $0.01 — Previous UTC-day OHLC candle for a crypto spot pair
- [GET /api/v1/crypto/{pair}/open-close](https://x402stock.xyz/api/v1/crypto/BTC-USD/open-close): $0.01 — Daily open and close for a crypto spot pair on a specific date

## On-chain perps (Hyperliquid)

- [GET /api/v1/perps](https://x402stock.xyz/api/v1/perps): $0.02 — Every on-chain perp in one call: funding rate, open interest, mark/oracle price, 24h volume
- [GET /api/v1/perps/{coin}](https://x402stock.xyz/api/v1/perps/BTC): $0.01 — Single on-chain perp: funding, open interest, mark/oracle price, 24h volume
- [GET /api/v1/perps/funding/{coin}](https://x402stock.xyz/api/v1/perps/funding/BTC): $0.01 — Historical funding-rate series for an on-chain perp
- [GET /api/v1/perps/predicted-funding](https://x402stock.xyz/api/v1/perps/predicted-funding): $0.02 — Predicted next-period funding for every coin across major perp venues
- [GET /api/v1/perps/orderbook/{coin}](https://x402stock.xyz/api/v1/perps/orderbook/BTC): $0.01 — L2 order book (aggregated price levels) for an on-chain perp
- [GET /api/v1/perps/candles/{coin}](https://x402stock.xyz/api/v1/perps/candles/BTC): $0.02 — Historical OHLCV candles for an on-chain perp at any interval
- [GET /api/v1/perps/account/{address}](https://x402stock.xyz/api/v1/perps/account/0x0000000000000000000000000000000000000000): $0.02 — On-chain perp account state for any address: positions, margin, open orders
- [GET /api/v1/perps/fills/{address}](https://x402stock.xyz/api/v1/perps/fills/0x0000000000000000000000000000000000000000): $0.02 — On-chain perp trade history (fills) for any address, most recent first
- [GET /api/v1/perps/overview/{coin}](https://x402stock.xyz/api/v1/perps/overview/BTC): $0.03 — On-chain perp 360 in one call: live context, funding history, order book, and price candles

## On-chain spot (Hyperliquid)

- [GET /api/v1/spot](https://x402stock.xyz/api/v1/spot): $0.02 — Every Hyperliquid spot token in one call: price, 24h volume, supply, market cap
- [GET /api/v1/spot/{token}](https://x402stock.xyz/api/v1/spot/PURR): $0.01 — Single Hyperliquid spot token: price, 24h volume, supply, market cap
- [GET /api/v1/spot/orderbook/{token}](https://x402stock.xyz/api/v1/spot/orderbook/PURR): $0.01 — L2 order book (aggregated price levels) for a Hyperliquid spot token
- [GET /api/v1/spot/candles/{token}](https://x402stock.xyz/api/v1/spot/candles/PURR): $0.02 — Historical OHLCV candles for a Hyperliquid spot token at any interval

## Solana on-chain

- [GET /api/v1/solana/token/{mint}](https://x402stock.xyz/api/v1/solana/token/So11111111111111111111111111111111111111112): $0.01 — On-chain SPL token facts for any Solana mint: supply, decimals, mint & freeze authority
- [GET /api/v1/solana/balance/{address}](https://x402stock.xyz/api/v1/solana/balance/So11111111111111111111111111111111111111112): $0.01 — Native SOL balance and account metadata for any Solana address
- [GET /api/v1/solana/holders/{mint}](https://x402stock.xyz/api/v1/solana/holders/So11111111111111111111111111111111111111112): $0.02 — Top holders of any Solana SPL token: largest accounts, owner wallets, % of supply
- [GET /api/v1/solana/jlp](https://x402stock.xyz/api/v1/solana/jlp): $0.02 — Jupiter JLP pool: AUM, virtual price, per-asset holdings, utilization & trader exposure

## Private / pre-IPO

- [GET /api/v1/private-stocks](https://x402stock.xyz/api/v1/private-stocks): $0.02 — Pre-IPO private company prices: Anthropic, OpenAI, SpaceX, Anduril and more in one call
- [GET /api/v1/private-stocks/{symbol}](https://x402stock.xyz/api/v1/private-stocks/ANTHROPIC): $0.01 — One pre-IPO private company's price and valuation (e.g. ANTHROPIC, SPACEX)

## Macro, rates & commodities

- [GET /api/v1/macro](https://x402stock.xyz/api/v1/macro): $0.05 — US macro dashboard in one call: Fed funds, CPI, PCE, jobs, GDP, and the Treasury yield curve
- [GET /api/v1/treasury-yields](https://x402stock.xyz/api/v1/treasury-yields): $0.01 — US Treasury par yield curve (1mo to 30yr) for the latest day or a date range
- [GET /api/v1/inflation](https://x402stock.xyz/api/v1/inflation): $0.02 — US CPI inflation: headline and core index with year-over-year percent
- [GET /api/v1/labor-market](https://x402stock.xyz/api/v1/labor-market): $0.02 — US labor market: unemployment, participation, payrolls, and wage growth
- [GET /api/v1/fed-funds](https://x402stock.xyz/api/v1/fed-funds): $0.01 — Effective federal funds rate (the Fed's policy rate), monthly, with recent history
- [GET /api/v1/gdp](https://x402stock.xyz/api/v1/gdp): $0.01 — US real GDP, quarterly, with quarter-over-quarter and year-over-year change
- [GET /api/v1/money-supply](https://x402stock.xyz/api/v1/money-supply): $0.01 — US M2 money supply, monthly, with month-over-month and year-over-year change
- [GET /api/v1/pce](https://x402stock.xyz/api/v1/pce): $0.02 — PCE inflation (the Fed's preferred gauge): headline and core index with year-over-year
- [GET /api/v1/fred/{series}](https://x402stock.xyz/api/v1/fred/vix): $0.01 — Key market-signal macro series from the Fed (FRED): VIX, yield-curve & credit spreads, breakevens, jobless claims, sentiment, mortgage rate, recession odds
- [GET /api/v1/cot](https://x402stock.xyz/api/v1/cot): $0.02 — Commitments of Traders snapshot: net futures positioning across major equity-index, metal, energy, FX, rates & crypto markets in one call
- [GET /api/v1/cot/{market}](https://x402stock.xyz/api/v1/cot/gold): $0.01 — Commitments of Traders for one futures market: long/short/net by trader group, with weekly changes and history
- [GET /api/v1/national-debt](https://x402stock.xyz/api/v1/national-debt): $0.01 — US national debt to the penny: total public debt outstanding with daily change
- [GET /api/v1/avg-interest-rates](https://x402stock.xyz/api/v1/avg-interest-rates): $0.01 — Average interest rate the US Treasury pays on its debt, by security type
- [GET /api/v1/exchange-rates](https://x402stock.xyz/api/v1/exchange-rates): $0.02 — Official US Treasury reporting rates of exchange for ~170 currencies
- [GET /api/v1/energy](https://x402stock.xyz/api/v1/energy): $0.02 — Energy commodities snapshot: WTI, Brent, natural gas, gasoline prices in one call
- [GET /api/v1/energy/{product}](https://x402stock.xyz/api/v1/energy/wti): $0.01 — One energy benchmark price with history: wti, brent, natural-gas, or gasoline
- [GET /api/v1/world-bank/country/{iso}](https://x402stock.xyz/api/v1/world-bank/country/US): $0.02 — Country macro snapshot: GDP, growth, inflation, unemployment, debt and more in one call
- [GET /api/v1/world-bank/{indicator}](https://x402stock.xyz/api/v1/world-bank/gdp): $0.01 — One World Bank indicator's annual time series for any country

## Government spending & politics

- [GET /api/v1/gov-contracts](https://x402stock.xyz/api/v1/gov-contracts): $0.02 — Federal contract & grant awards to a company (USAspending.gov)
- [GET /api/v1/gov-awards](https://x402stock.xyz/api/v1/gov-awards): $0.02 — Latest large new federal awards across all recipients
- [GET /api/v1/congress-trades](https://x402stock.xyz/api/v1/congress-trades): $0.03 — US congressional stock trades (House & Senate) from STOCK Act disclosures: who traded what, when, and how much

## News & market sentiment

- [GET /api/v1/news](https://x402stock.xyz/api/v1/news): $0.02 — Latest news articles, optionally filtered by ticker
- [GET /api/v1/news-sentiment](https://x402stock.xyz/api/v1/news-sentiment): $0.02 — Global news attention & tone for a company or topic (GDELT)
- [GET /api/v1/trending/reddit](https://x402stock.xyz/api/v1/trending/reddit): $0.01 — Trending tickers on Reddit (last 24h): the most-mentioned stocks, crypto, or both
- [GET /api/v1/trending/4chan](https://x402stock.xyz/api/v1/trending/4chan): $0.01 — Trending tickers on 4chan /biz/ (last 24h): the most-mentioned by post volume
- [GET /api/v1/fear-greed](https://x402stock.xyz/api/v1/fear-greed): $0.02 — US stock Fear & Greed index now: score, rating, 5 components, backtest
- [GET /api/v1/fear-greed/history](https://x402stock.xyz/api/v1/fear-greed/history): $0.02 — Full daily history of the US stock Fear & Greed index (2016–present)
- [GET /api/v1/fear-greed/crypto](https://x402stock.xyz/api/v1/fear-greed/crypto): $0.01 — Crypto Fear & Greed index with BTC/ETH prices and a stock comparison
- [GET /api/v1/fear-greed/regime](https://x402stock.xyz/api/v1/fear-greed/regime): $0.02 — Combined market regime: Fear & Greed + VIX + insider + liquidity
- [GET /api/v1/fear-greed/liquidity](https://x402stock.xyz/api/v1/fear-greed/liquidity): $0.01 — US net liquidity gauge (Fed balance sheet − TGA − RRP) with trend

## Other endpoints

- [GET /api/v1/research/{ticker}](https://x402stock.xyz/api/v1/research/AAPL): $0.75 — AI equity-research report: bull/bear case, valuation, catalysts, risks, and a per-signal read-out for one stock
- [GET /api/v1/score/squeeze/{ticker}](https://x402stock.xyz/api/v1/score/squeeze/AAPL): $0.15 — Short-squeeze score (0–100): a weighted gauge of short interest, days-to-cover, short volume, FTDs and spark
- [GET /api/v1/score/insider/{ticker}](https://x402stock.xyz/api/v1/score/insider/AAPL): $0.15 — Insider-conviction score (0–100): net Form 4 flow, role weighting, cluster buys, Form 144 and 13D
- [GET /api/v1/score/factors/{ticker}](https://x402stock.xyz/api/v1/score/factors/AAPL): $0.15 — Quant factor score: value, quality, growth and momentum sub-scores plus a composite (0–100)
- [GET /api/v1/portfolio/xray](https://x402stock.xyz/api/v1/portfolio/xray): $0.25 — Portfolio risk x-ray: concentration, sector & market-cap exposure, and weighted performance in one call
- [GET /api/v1/screener/smart](https://x402stock.xyz/api/v1/screener/smart): $0.20 — Natural-language stock screener: describe what you want, get a ranked shortlist with per-name rationale

## Free endpoints (no payment)

- [GET /api/v1/market-status](https://x402stock.xyz/api/v1/market-status): free — Current US market status (open / closed / pre / post)
- [GET /api/v1/market-holidays](https://x402stock.xyz/api/v1/market-holidays): free — Upcoming US market holidays & early closes

## Discovery & machine-readable specs

- [OpenAPI 3.1 spec](https://x402stock.xyz/openapi.json): every endpoint with parameters, schemas, and per-endpoint x402 pricing
- [llms.txt](https://x402stock.xyz/llms.txt): condensed agent guidance and endpoint index
- [x402 payable resource catalog](https://x402stock.xyz/.well-known/x402): the x402/Bazaar resource list (also at https://x402stock.xyz/.well-known/x402.json)
- [AgentCash service manifest](https://x402stock.xyz/.well-known/agentcash): supported payment protocols, networks, and payee