patternfetch API & MCP reference

Quickstart

# 0) no-signup demo — a real brief, no key
curl -X POST https://patternfetch.com/v1/demo \
  -H "Content-Type: application/json" \
  -d '{"ticker":"BTC/USDT","timeframe":"4h"}'

# 1) free key ($0.05 starter credit)
curl -X POST https://patternfetch.com/v1/keys \
  -H "Content-Type: application/json" -d '{"email":"you@example.com"}'

# 2) a brief
curl -X POST https://patternfetch.com/v1/brief \
  -H "Authorization: Bearer pf_…" -H "Content-Type: application/json" \
  -d '{"ticker":"BTC/USDT","timeframe":"4h"}'

Authentication

All paid endpoints take a bearer key: Authorization: Bearer pf_…. Get one free (below). Agents can also connect over MCP with OAuth — no key to paste. Keys are shown once; store them. Every response carries an X-Disclaimer header.

POST /v1/brief POST $0.01

The full token-compact market-state brief for a ticker + timeframe.

Request

{ "ticker": "BTC/USDT", "timeframe": "4h", "limit": 200 }

Field	Type	Notes
ticker	string	required · crypto pair, e.g. BTC/USDT
timeframe	string	required · one of 1m 5m 15m 1h 4h 1d
limit	int	optional · candles to analyze (default 200, min 20)

Response

{
  "header": { "sym":"BTC/USDT","tf":"4h","src":"binance","n":200,
              "t0":1747094400000,"t1":1747958400000 },
  "codec": { "rows":"60125.4,60480,59890.1,60310.7,1284;…",
             "sax":"dcefdcbe", "precision":1 },
  "analysis": {
    "patterns":[{"name":"double_bottom","confidence":0.86,"at":158,"span":14}],
    "levels":{ "support":[{"price":59820.4,"strength":1}],
               "resistance":[{"price":63450.8,"strength":1}] },
    "regime":{ "trend":"up","strength":0.42,"volPct":2.13 },
    "indicators":{ "rsi":{"v":58.34,"state":"neutral"},
                   "ema":{"v":61240.77,"state":"above_20_50"} },
    "nl":"BTC/USDT: uptrend (moderate), +1.94% last 4h, RSI 58.34 (neutral), double_bottom (conf 0.86)."
  },
  "disclaimer":"… informational only, not advice …",
  "methodologyUrl":"https://patternfetch.com/methodology"
}

codec.rows = compact candles o,h,l,c,v per row (no per-row timestamp; the series is bound by header.t0/t1). codec.sax = an a–g shape fingerprint. Pattern names: bullish_engulfing, bearish_engulfing, hammer, doji, double_top, double_bottom, head_and_shoulders. See methodology for exactly how each field is computed.

POST /v1/delta POST $0.008 · $0.001 empty

Only what changed since your last brief for this ticker+timeframe (trend flips, new patterns, RSI-state changes). Ideal for polling agents — when nothing material moved it returns changed:false and is billed at the cheaper empty rate.

// request
{ "ticker":"BTC/USDT", "timeframe":"4h" }

// changed → includes the full current brief
{ "delta": { "changed":true, "sym":"BTC/USDT", "tf":"4h",
             "notes":["trend range -> up","new pattern(s): double_bottom"] },
  "brief": { /* same shape as /v1/brief */ } }

// nothing changed → no brief, billed $0.001
{ "delta": { "changed":false, "sym":"BTC/USDT", "tf":"4h", "notes":[] } }

POST /v1/candles POST $0.005

The compact candle codec only — no analysis. Cheapest way to get raw-ish OHLCV in a token-efficient form.

{ "header":{ "sym":"BTC/USDT","tf":"4h","src":"binance","n":200 },
  "codec":{ "rows":"60125.4,60480,59890.1,60310.7,1284;…","sax":"dcefdcbe","precision":1 },
  "disclaimer":"…" }

POST /v1/analogs POST $0.05

Historical windows whose shape resembles the current price action, and the full distribution of what followed over a fixed forward horizon (winners and losers). Not a prediction, not a strategy backtest.

// request
{ "ticker":"BTC/USDT", "timeframe":"4h", "window":32, "horizon":20 }

// response
{ "sym":"BTC/USDT","tf":"4h","window":32,
  "distribution":{ "n":18,"horizon":20,"winRate":0.6111,
                   "median":0.0214,"mean":0.0307,"min":-0.0892,"max":0.1645 },
  "matches":18,
  "note":"Full outcome distribution incl. losers. Not a prediction.",
  "disclaimer":"…" }

Returns (e.g. median) are fractions: 0.0214 = +2.14%. window and horizon default to 32 / 20, range [2,500].

POST /v1/demo POST free

A real brief with no key — the same body and output as /v1/brief. IP rate-limited; never billed. Great for a first taste and for the live playground.

POST /v1/keys POST free

curl -X POST https://patternfetch.com/v1/keys \
  -H "Content-Type: application/json" -d '{"email":"you@example.com"}'
// -> { "key":"pf_…", "disclaimer":"…" }   (key shown once; $0.05 credit granted)

GET /v1/platforms · GET /v1/status GET free

/v1/platforms returns the capability matrix (assets, timeframes, endpoints, limits). /v1/status returns a small health object. /healthz is a bare liveness check. None require a key or are geoblocked.

MCP server

Streamable HTTP at POST https://patternfetch.com/mcp. Tools: patternfetch_brief, patternfetch_delta, patternfetch_analogs, patternfetch_capabilities. Discovery (initialize, tools/list) is free; a tools/call needs a key (via OAuth or a Bearer header) and is billed like the matching REST endpoint.

{
  "mcpServers": {
    "patternfetch": {
      "url": "https://patternfetch.com/mcp",
      "headers": { "Authorization": "Bearer pf_…" }
    }
  }
}

Claude Desktop / Cursor over a local bridge: npx mcp-remote https://patternfetch.com/mcp --header "Authorization: Bearer pf_…". One-liner: claude mcp add --transport http patternfetch https://patternfetch.com/mcp --header "Authorization: Bearer pf_…".

OAuth — one-click connect (no key to paste)

patternfetch implements OAuth for MCP, so Smithery, Claude.ai, Cursor and Claude Desktop can connect with zero manual key handling: add the server URL, click Authorize once, and patternfetch mints a free-tier key for you behind the scenes.

Discovery / endpoint	What it is
/.well-known/oauth-protected-resource	RFC 9728 — points clients at the auth server
/.well-known/oauth-authorization-server	RFC 8414 — endpoints + PKCE (S256) support
POST /oauth/register	RFC 7591 dynamic client registration
GET/POST /oauth/authorize	consent → mint free key → auth code
POST /oauth/token	PKCE exchange → access token (a pf key)

In Claude.ai: Settings/Customize → Connectors → Add custom connector → paste https://patternfetch.com/mcp → Authorize. The unauthenticated /mcp 401 also carries a WWW-Authenticate header so compliant clients discover OAuth automatically.

Billing & top-up

Calls are metered in micros (millionths of USD). When credit runs out, paid calls return PAYMENT_REQUIRED. Top up two ways:

• x402 — POST /v1/topup with a USDC (Base) payment. No account, no human; an agent settles it on its own. Discoverable at /.well-known/x402.json.
• Stripe — POST /v1/checkout (with your key) returns a hosted checkout URL.

Errors

Errors are JSON: { "error":"CODE", "message":"…" } with a matching HTTP status.

Code	HTTP	Meaning
INVALID_PARAM	400	bad/missing ticker, timeframe, email, or value out of range
UNAUTHORIZED	401	missing or invalid bearer key
PAYMENT_REQUIRED	402	insufficient credit — top up via x402 or Stripe
GEO_BLOCKED	451	not offered to US persons
RATE_LIMITED	429	too many requests (or demo limit reached)
INSUFFICIENT_DATA	422	fewer than 20 candles available for that pair/timeframe
NOT_FOUND	404	no such route
UPSTREAM_ERROR	502	market-data source error

Rate limits & notes

• Per-key rate limit on paid endpoints; demo is limited per IP. Back off on 429.
• Assets: crypto spot. Source: Binance. Timeframes: 1m–1d.
• Request body cap: 64 KB. All responses include the X-Disclaimer header.
• Service is not offered to US persons.

→ Try it live · Pricing · Methodology