# patternfetch

> Agent-first API + MCP. One call turns a stock, ETF, or crypto ticker + timeframe into a token-compact
> market-state brief: compact candles, detected patterns, support/resistance, trend/regime,
> interpreted indicators, and a one-line summary — so an LLM agent never has to dump raw OHLCV
> into its context (saving tokens and avoiding numeric hallucination).
> Impersonal market data, NOT investment advice.

## Try it (free, no signup)
- POST /v1/demo {ticker, timeframe} -> a real market-state brief, no key (rate-limited, never billed).
- Live playground: https://patternfetch.com/try

## Endpoints
- POST /v1/brief   {ticker, timeframe} -> full market-state brief (candles + patterns + S/R + regime + indicators + 1-line `nl` summary). $0.01
- POST /v1/multi   {ticker, timeframes[]} -> multi-timeframe view: a brief per timeframe (default 1h,4h,1d) + cross-timeframe trend alignment/divergence. $0.025
- POST /v1/delta   {ticker, timeframe} -> only what changed since your last brief (token-minimal for polling; $0.001 when nothing changed). $0.008
- POST /v1/candles {ticker, timeframe} -> compact candle codec only (rows + SAX shape signature). $0.005
- POST /v1/analogs {ticker, timeframe} -> historical analogs as a FULL outcome distribution (n, winRate, median, mean, min, max). Not a prediction. $0.05
- POST /v1/scan    {assetClass?, regime?, pattern?, tf?, minLift?, minBaseRate?, limit?} -> SCREENER: discovery, not lookup. Scans US stocks, ETFs and crypto for the tickers currently in a given regime or printing a chart/candlestick pattern, RANKED by the honest backtested base rate + 95% CI — so your model finds the few real signals instead of being handed one ticker at a time. $0.02
- POST /v1/demo    {ticker, timeframe} -> free no-signup brief (rate-limited).
- POST /v1/keys    {email} -> self-serve API key + $3.00 starter credit (300 briefs), no card. Staged: at least $0.50 is usable immediately, confirming your email address releases the remainder (where confirmation is not required, the full $3.00 lands at signup). Confirming never gates API access — it only releases the rest of the credit.
- POST /v1/recover {email} -> lost your key? We only store a hash, so it cannot be re-sent. This mails a single-use link; opening it issues a NEW key (shown once) and DEACTIVATES all previous keys on the account. Credit balance untouched. Nothing changes until the link is opened, so an unrequested mail can be ignored. The response is identical whether or not the address is registered.
- POST /v1/topup   -> x402 (USDC on Base) credit top-up, no account.
- POST /v1/checkout -> Stripe hosted checkout URL ($5 credit top-up).
- POST /v1/subscribe -> Stripe subscription checkout: Studio, $19/month, 2,500 briefs ($25 of usage) included per month, then pay-per-call from credit.
- POST /v1/portal -> Stripe billing-portal URL (single-use, short-lived): cancel Studio, replace an expired card, update billing email/address/VAT id, download invoices. Works for any account that has paid once, not only subscribers. Cancellation takes effect at the END of the paid period, so the remaining included allowance stays spendable. 404 if the account has never paid.
- GET  /v1/platforms -> capabilities (assets, timeframes, endpoints). GET /v1/status, /healthz -> health.

## Timeframes & assets
- Assets: US stocks, ETFs and crypto — one schema. Crypto is Binance spot (realtime); stocks & ETFs are Yahoo (split & dividend adjusted, delayed/EOD). Timeframes: 1m, 5m, 15m, 30m, 1h, 4h, 1d, 1w. Min 20 candles.

## Auth & payment
- Bearer API key on paid endpoints: `Authorization: Bearer pf_...` (POST /v1/keys to get one free).
- The key is shown ONCE and only its hash is stored. Signing up again with the same address does not return it — the starter credit is one per address, so a repeat signup yields a separate empty account. Lost keys go through POST /v1/recover (mail-bound; issues a replacement and revokes the old ones).
- Pay per call via x402 (USDC on Base, no account) or Stripe (cards). Discovery at /.well-known/x402.json.

## MCP (Streamable HTTP)
- Endpoint: POST https://patternfetch.com/mcp
- Tools (6): patternfetch_brief, patternfetch_multi, patternfetch_delta, patternfetch_analogs, patternfetch_scan, patternfetch_capabilities.
- Discovery (initialize, tools/list) is FREE — no key. Only tools/call needs a key.

## OAuth (one-click connect, no key to paste)
- Smithery, Claude.ai, Cursor and Claude Desktop can connect via OAuth: add https://patternfetch.com/mcp,
  click Authorize once, and patternfetch mints a free-tier key automatically.
- Discovery: /.well-known/oauth-protected-resource, /.well-known/oauth-authorization-server (PKCE S256).

## Key docs
- Home: https://patternfetch.com/
- API reference: https://patternfetch.com/docs
- How-to / integration: https://patternfetch.com/how-to
- Pricing: https://patternfetch.com/pricing
- Methodology (how signals are computed): https://patternfetch.com/methodology
- Pattern base-rate study (the measurement, in full): https://patternfetch.com/pattern-base-rates-study
  Six classic chart/candlestick patterns measured across 105 pattern x timeframe x confidence-band
  categories and 373,748 non-overlapping occurrences (117 US stocks & ETFs, 10 crypto pairs, 10-bar
  horizon, snapshot 2026-07-18). Every hit rate is read against the PATTERN-FREE BASELINE of the same
  market/timeframe/horizon rather than against 50%: US stocks close up 57.8% of the time over 10 days
  with no pattern present, so a "58% bullish pattern" has added nothing. Result: no category's lift
  survives clustering by calendar day plus correction for 105 tests. On the 60 stock categories, zero
  clear even an unadjusted interval; 3 crypto categories do, which is FEWER than the ~5.3 expected by
  chance. Crypto is the control: it has no drift, and the apparent bullish/bearish split vanishes with it.
  Includes full method, per-category tables and a stated limitations section.
- Token-cost study (the measurement, in full): https://patternfetch.com/token-cost-study
  A MEASURED comparison (not an estimate) of what raw OHLCV costs an LLM versus a market-state brief.
  Raw candles from the Yahoo chart endpoint vs a brief from POST /v1/demo, counted with the cl100k_base
  tokenizer (o200k_base agrees) across 8 tickers/timeframes. For the exact 120-candle window a brief
  summarizes: raw = ~3,111 tokens (CSV) / ~4,541 (JSON); the actionable market-state read = ~299 tokens
  (272-314) — a ~10-15x reduction. The homepage's ~800x / 400K / ~$6-a-call figures need a LARGE raw
  history: at ~25 tokens/candle, 400,000 tokens is ~16,000 candles (read then ~1,000x smaller). Honest
  caveats stated: the full keyless demo payload is ~12,327 tokens (it ships the candle codec + base-rate
  evidence), the tokenizer is GPT-family (Claude/Gemini differ), and the brief is a lossy interpretation.
  Includes cost in dollars at published Gemini/Anthropic prices, the context-quality literature, and limits.
- Compare vs raw OHLCV APIs: https://patternfetch.com/compare-market-data-apis
- Feature pages (crypto): /crypto-candlestick-patterns-api, /crypto-chart-pattern-detection-api, /support-resistance-levels-api, /technical-indicators-api
- Feature pages (stocks & ETFs): /stock-candlestick-patterns-api, /stock-chart-pattern-detection-api, /stock-support-resistance-levels-api, /stock-technical-indicators-api
- Cross-asset: /stock-crypto-market-scanner-api (the screener)
- Guides/answers: /llm-token-cost-ohlcv-candles, /ai-agent-pay-api-x402-usdc, /langchain-crewai-market-context-tool, /trading-agent-indicator-hallucination-fix, /market-regime-api-for-ai-agents, /market-data-tokens-per-call-benchmark, /token-cost-study
- Glossary (term definitions): https://patternfetch.com/glossary
- Full single-file reference for LLMs: https://patternfetch.com/llms-full.txt
- OpenAPI: https://patternfetch.com/openapi.json

## Legal
- Impersonal market data + algorithmic signals, informational only, NOT investment/financial/legal/tax advice,
  not personalized, non-executing. See /disclaimer and /terms.