Docs Terminal Pricing Sign up free
Getting Started
Introduction Authentication Rate Limits Errors
Endpoints
POSTSimilar Patterns GETCandles GETChart Patterns POSTAI Analysis GETSymbols GETUsage GETHealth GETPlans
Concepts
Relevance Tiers Volatility Context Multi-Timeframe Confidence Score Directional Consensus
Resources
Asset Coverage

Introduction

ChartMatch is a REST API that finds historically similar chart patterns across 500+ instruments spanning crypto, forex, commodities, indices, and stocks. For each match, it returns what happened next — with confidence scores, multi-timeframe outcomes, directional consensus, and volatility context.

Base URL:

https://chartmatch.io

All responses are JSON. All timestamps are UTC. Prices use the source's native precision.

Authentication

Every request requires an API key sent via the X-API-Key header. Get your key from the dashboard after signing up.

Each account can have up to 5 API keys. Usage is aggregated across all keys — if your plan allows 2,000 calls/month, that's shared across all your keys.

Rate Limits

Rate limits are per account, not per key. Limits reset on the 1st of each month (UTC).

PlanCalls / monthPrice
Free5$0
Pro2,000$19.99/mo
Builder30,000$49.99/mo

When you exceed your limit, the API returns 429 Too Many Requests. Check remaining calls with GET /v1/usage.

Errors

The API uses standard HTTP status codes. Error responses include a JSON body with detail.

CodeMeaning
400Bad request — invalid parameters
401Missing or invalid API key
403Feature not available on your plan (e.g., cross-asset on Free)
429Rate limit exceeded
500Server error

POST /v1/similar-patterns

Find historically similar chart patterns for a given symbol. Returns matches ranked by similarity with outcome data, confidence scores, and relevance classification.

Parameters

NameTypeDescription
symbol required string Symbol to query. Examples: "BTCUSDT", "GC=F", "AAPL"
lookback optional int Number of recent candles to use as the query pattern. Default: 30. Range: 10–200.
top_n optional int Number of matches to return. Default: 10. Range: 1–50.
outcome_candles optional int Forward candles for outcome computation. Default: 30. Range: 1–200.
relevance_filter optional string Filter by relevance tier. Default: none (pure top-N).
  • "same_pair" — same asset only
  • "same_asset_class" — same category only
  • "cross_asset" — cross-asset only
  • "balanced" — guaranteed mix (40/30/30)
categories optional string[] Filter by asset class. Values: "crypto", "forex", "commodity", "index", "stock". Free tier: crypto only.
min_volatility optional float Minimum annualized volatility of matched window. Example: 0.3 = 30%.
max_volatility optional float Maximum annualized volatility. Example: 1.0 = 100%.
normalize optional string Normalization method. "returns" (default) or "zscore". Zscore adjusts for cross-asset volatility differences.
interval optional string Candle interval. Default: "1d". Options: "1d", "1w", "1M".

Response Fields — Match Object

symbolMatched instrument symbol
nameHuman-readable name (e.g., "BTC", "Coffee Futures")
categoryAsset class: crypto, forex, commodity, index, stock
relevance"same_pair" (same asset), "same_asset_class" (same category), "cross_asset" (cross-asset)
similarityDTW similarity score (0–1, higher = more similar)
confidencePercentile rank — "top 0.003%" means this match beat 99.997% of all windows
volatilityAnnualized volatility of the matched window
volatility_ratioWindow vol ÷ asset's historical avg vol. 1.0 = normal, 2.0+ = extreme
volatility_context"calm" (<0.7x), "typical" (0.7–1.3x), "elevated" (1.3–2.0x), "extreme" (>2.0x)
periodDate range of the matched pattern
outcome.returnTotal return over outcome_candles period
outcome.max_gainBest point reached during outcome period
outcome.max_drawdownWorst point reached during outcome period
outcome.timeframesReturns at 7d, 14d, 30d (when available)
rankPosition in results (1 = best match)

Response Fields — Outcome Summary

direction"bullish", "bearish", or "neutral" — majority vote across all matches
consensusHuman-readable: "7 of 10 bullish (70%)"
bullish_percentagePercentage of matches with positive returns
avg_returnMean return across all matches
by_relevanceStats broken down by relevance tier (high/medium/low)
by_timeframeWin rate and avg return at 7d, 14d, 30d
by_categoryStats per asset class with avg gain, drawdown, best/worst

GET /v1/candles

Retrieve OHLCV candle data for any instrument. Useful for charting or building your own analysis on top of ChartMatch data.

Query Parameters

NameTypeDescription
symbol required string Symbol to query. Examples: "BTCUSDT", "AAPL", "GC=F"
interval optional string Candle interval. Default: "1d". Options: "1d", "1w", "1M".
limit optional int Number of candles to return. Default: 200. Max: 500.
start optional int Start timestamp in milliseconds. When omitted, returns the most recent candles.
end optional int End timestamp in milliseconds.

Response Fields

symbolQueried symbol
intervalCandle interval
countNumber of candles returned
candles[].tOpen time (ms timestamp)
candles[].oOpen price
candles[].hHigh price
candles[].lLow price
candles[].cClose price
candles[].vVolume

GET /v1/patterns

Detect classical chart patterns (double top/bottom, head & shoulders, triangles, flags, wedges, channels) on any symbol.

Query Parameters

NameTypeDescription
symbol required string Symbol to scan.
interval optional string Candle interval. Default: "1d".
lookback optional int Number of candles to scan. Default: 100.

Response Fields

patterns_foundNumber of patterns detected
patterns[].namePattern name (e.g., "Double Bottom", "Rising Wedge")
patterns[].direction"bullish" or "bearish"
patterns[].confidenceConfidence score (0–1)
patterns[].status"forming" or "completed"
patterns[].candle_spanNumber of candles the pattern spans
patterns[].key_levelsImportant price levels (support, resistance, neckline, etc.)
patterns[].descriptionHuman-readable description of the pattern

POST /v1/analyze

AI-powered analysis of a pattern match result. Generates a written interpretation of similarity data, outcome context, and what the match means for the queried symbol.

Parameters

NameTypeDescription
query_symbol required string The symbol that was queried (e.g., "BTCUSDT")
match required object A single match object from the /v1/similar-patterns response
outcome_summary optional object The outcome_summary from the similar-patterns response, for broader context

Response

analysisAI-generated text analysis of the match
providerWhich AI provider was used

GET /v1/symbols

List all available instruments. Free tier users see crypto only.

Query Parameters

NameTypeDescription
category optional string Filter by asset class: "crypto", "forex", "commodity", "index", "stock"

GET /v1/usage

Check your current API usage for the billing period.

Response

tierYour current plan (free, pro, builder)
calls_this_monthTotal calls made this billing period
calls_limitMaximum calls allowed
remainingCalls remaining before rate limit

GET /health

Status check. No authentication required. Returns symbol and candle counts to verify the database is populated.

GET /v1/billing/plans

List all available subscription plans with pricing and features. No authentication required.

Relevance Tiers

Every match is classified into one of three relevance tiers based on the relationship between the query symbol and the matched symbol:

TierMeaning
same_pairSame asset — BTC vs BTC history. Same market dynamics, same trader psychology. Strongest relevance for prediction.
same_asset_classSame category — BTC vs ETH (both crypto), Gold vs Silver (both commodities). Assets that tend to move together for fundamental reasons.
cross_assetCross-asset — BTC vs S&P 500, ETH vs Oil. Statistical shape match only. Useful for research and discovery, not prediction.

Use the relevance_filter parameter to search only a specific tier, or use "balanced" to get a guaranteed mix of all three.

Volatility Context

Each match includes a volatility_ratio — the matched window's annualized volatility divided by the asset's historical average volatility.

BTC moving 10% in a month → volatility_ratio: 1.0 (normal for BTC).

S&P 500 moving 10% in a month → volatility_ratio: 3.0 (once-in-a-decade event).

The volatility_context field provides a human-readable label:

LabelRatioMeaning
calm< 0.7xUnusually quiet period for this asset
typical0.7x – 1.3xTypical volatility
elevated1.3x – 2.0xHigher than usual
extreme> 2.0xRare, crisis-level volatility for this asset

Use min_volatility / max_volatility to filter matches by absolute volatility level.

Multi-Timeframe Outcomes

Each match's outcome includes sub-timeframes at 7, 14, and 30 candles (when data is available). This reveals whether a pattern is bullish short-term but bearish long-term, or vice versa.

The by_timeframe section in the outcome summary shows aggregate win rates and average returns at each horizon across all matches.

Confidence Score

The confidence field shows the match's percentile rank. "top 0.003%" means this match was #1 out of ~300,000 windows compared — it beat 99.997% of all possible patterns in the database.

This gives context to the raw similarity score. A similarity of 0.93 is meaningless without knowing the distribution — is that top 1% or top 40%?

Directional Consensus

The outcome summary includes a majority-vote direction field: how many matches went up vs down after the pattern ended.

"7 of 10 bullish (70%)" means 70% of the historically similar patterns led to positive returns. Combined with by_relevance, you can see whether the bullish consensus holds across same-asset and cross-asset matches or only in one tier.

Asset Coverage

The database covers 500+ instruments across 6 asset classes, synced daily.

CategoryCountSource
crypto370+ pairsBinance (USDT pairs by volume)
forex25 pairsYahoo Finance (EUR, GBP, JPY, CHF, AUD…)
commodity26 futuresYahoo Finance (Gold, Oil, Coffee, Corn…)
index24 indicesYahoo Finance (S&P 500, NASDAQ, DAX, Nikkei…)
etf30 fundsYahoo Finance (SPY, QQQ, GLD, XLF…)
stock150+ equitiesYahoo Finance (AAPL, NVDA, TSLA, AMZN…)

Total: ~10,000,000+ candles at daily resolution, with weekly and monthly also available.

Authentication
# Include in every request
X-API-Key: cm_your_api_key_here
POST /v1/similar-patterns
cURL
Python
JavaScript
curl -X POST https://chartmatch.io/v1/similar-patterns \
  -H "X-API-Key: cm_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "symbol": "BTCUSDT",
    "lookback": 30,
    "top_n": 10,
    "relevance_filter": "balanced"
  }'
Response
{
  "query": {
    "symbol": "BTCUSDT",
    "lookback": 30,
    "outcome_candles": 30
  },
  "search_stats": {
    "symbols_searched": 287,
    "windows_compared": 302841,
    "elapsed_seconds": 5.42
  },
  "matches": [
    {
      "symbol": "BTCUSDT",
      "relevance": "same_pair",
      "similarity": 0.9487,
      "confidence": "top 0.003%",
      "volatility_ratio": 1.12,
      "outcome": {
        "return": "+15.21%",
        "timeframes": {
          "7d": {"return": "+4.8%"},
          "14d": {"return": "+9.4%"},
          "30d": {"return": "+15.2%"}
        }
      },
      "rank": 1
    },
    ...
  ],
  "outcome_summary": {
    "direction": "bullish",
    "consensus": "7 of 10 bullish",
    "bullish_percentage": "70.00%",
    "avg_return": "+8.73%"
  }
}
GET /v1/candles
curl "https://chartmatch.io/v1/candles?symbol=BTCUSDT&limit=30" \
  -H "X-API-Key: cm_your_key"
Response
{
  "symbol": "BTCUSDT",
  "interval": "1d",
  "count": 30,
  "candles": [
    {
      "t": 1711929600000,
      "o": 69523.41,
      "h": 71024.00,
      "l": 69100.50,
      "c": 70812.33,
      "v": 24518.72
    }, ...
  ]
}
GET /v1/patterns
curl "https://chartmatch.io/v1/patterns?symbol=ETHUSDT&lookback=100" \
  -H "X-API-Key: cm_your_key"
Response
{
  "symbol": "ETHUSDT",
  "patterns_found": 2,
  "patterns": [
    {
      "name": "Double Bottom",
      "direction": "bullish",
      "confidence": 0.82,
      "status": "completed",
      "candle_span": 34
    }, ...
  ]
}
POST /v1/analyze
curl -X POST https://chartmatch.io/v1/analyze \
  -H "X-API-Key: cm_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "query_symbol": "BTCUSDT",
    "match": { ...match object... },
    "outcome_summary": { ...summary... }
  }'
Response
{
  "analysis": "This match shows BTCUSDT repeating
  a pattern from March 2024, where...",
  "provider": "vertex"
}
GET /v1/symbols
curl https://chartmatch.io/v1/symbols?category=crypto \
  -H "X-API-Key: cm_your_key"
Response
{
  "count": 206,
  "symbols": [
    {
      "symbol": "BTCUSDT",
      "name": "BTC",
      "source": "binance",
      "category": "crypto"
    }, ...
  ]
}
GET /v1/usage
curl https://chartmatch.io/v1/usage \
  -H "X-API-Key: cm_your_key"
Response
{
  "tier": "pro",
  "calls_this_month": 142,
  "calls_limit": 2000,
  "remaining": 1858
}
GET /health
curl https://chartmatch.io/health
Response
{
  "status": "ok",
  "symbols": 287,
  "candles": 374992
}
ChartMatch provides historical data analysis for educational and research purposes only. It does not constitute financial advice, investment recommendations, or trading signals. Past patterns do not guarantee future results.