📊

Docs/Volatility API

Volatility API

3 endpoints · ATR time-series · Spike detection · Day × Hour heatmap · Starter plan and above

Volatility Spikes HeatmapBase path GET /api/v1/volatility/*

🔑

Starter plan and above

All volatility endpoints require an active paid plan — Free plan access is not supported. Authentication is via the apiKey query parameter.

GET

/api/v1/volatility

Starter+

Returns a time-series of four complementary volatility metrics for a given symbol and timeframe: raw ATR, ATR%, Bollinger Band Width, and Historical Volatility. Results are returned newest-first.

Query Parameters

Name	Type	Description
apiKey*	string	Your API key.
symbolCode*	string	Symbol identifier (e.g. BTCUSD, XAUUSD).
timeFrame*	string	Candle interval: M1 · M5 · M15 · H1 · H4 · D1.
period	integer	Lookback window for ATR, Band Width, and Historical Volatility. Range 2–500. Default: 14.

Response Fields — 200 OK

Field	Type	Description
openTime	DateTimeOffset	Candle open timestamp (UTC).
atr	decimal	Average True Range — Wilder smoothed over period candles.
atrPercent	decimal	ATR as a percentage of closing price: ATR ÷ Close × 100.
bandWidth	decimal	Bollinger Band Width: (Upper − Lower) ÷ Middle × 100 — proxy for price expansion.
historicalVolatility	decimal	Rolling std dev of log returns over period candles, expressed as a percentage.

Request

GET /api/v1/volatility

GEThttps://api.realmarketapi.com/api/v1/volatility?apiKey=YOUR_API_KEY&symbolCode=BTCUSD&timeFrame=H1&period=14

Response — 200 OK

response.json

{
  "data": [
    {
      "openTime": "2025-06-01T08:00:00+00:00",
      "atr": 1234.560000,
      "atrPercent": 1.8432,
      "bandWidth": 7.2418,
      "historicalVolatility": 0.9751
    }
  ],
  "totalCount": 1
}

Code examples

volatility.js

const BASE    = "https://api.realmarketapi.com"
const API_KEY = "YOUR_API_KEY"
const PERIOD  = 14

const url = new URL("/api/v1/volatility", BASE)
url.searchParams.set("apiKey",     API_KEY)
url.searchParams.set("symbolCode", "BTCUSD")
url.searchParams.set("timeFrame",  "H1")
url.searchParams.set("period",     String(PERIOD))

const res = await fetch(url.toString())
if (!res.ok) throw new Error("Request failed: " + res.status)

const { data } = await res.json()
for (const point of data) {
  console.log(point.openTime, "ATR:", point.atr, "HV:", point.historicalVolatility)
}

▶️

Try it live in the Playground

Run a live /api/v1/volatility request with your API key — see the real response instantly in your browser.

Open Playground

GET

/api/v1/volatility/spikes

Starter+

Scans the full ATR series and returns only the candles where ATR exceeded a given multiple of the series average. Useful for identifying unusual bursts of market activity — news events, liquidity gaps, or panic-driven moves.

💡Only candles where atr ≥ spikeMultiplier × atrAverage are included. The direction field tells you whether that spike candle closed as Bullish, Bearish, or Neutral. Results are returned newest-first.

Query Parameters

Name	Type	Description
apiKey*	string	Your API key.
symbolCode*	string	Symbol identifier (e.g. BTCUSD, XAUUSD).
timeFrame*	string	Candle interval: M1 · M5 · M15 · H1 · H4 · D1.
period	integer	ATR lookback period. Range 2–500. Default: 14.
spikeMultiplier	decimal	Minimum ratio of candle ATR to series average ATR required to classify as a spike. Range 1.1–10.0. Default: 2.0.

Response Fields — 200 OK

Field	Type	Description
openTime	DateTimeOffset	Candle open timestamp (UTC).
atr	decimal	ATR value at the spike candle.
atrAverage	decimal	Mean ATR across the entire series used for comparison.
multiplierReached	decimal	atr ÷ atrAverage — how many times above average the spike was.
direction	string	Candle direction: "Bullish", "Bearish", or "Neutral".

Request

GET /api/v1/volatility/spikes

GEThttps://api.realmarketapi.com/api/v1/volatility/spikes?apiKey=YOUR_API_KEY&symbolCode=BTCUSD&timeFrame=H1&period=14&spikeMultiplier=2.0

Response — 200 OK

response.json

{
  "data": [
    {
      "openTime": "2025-05-12T14:00:00+00:00",
      "atr": 3512.880000,
      "atrAverage": 1204.320000,
      "multiplierReached": 2.92,
      "direction": "Bearish"
    }
  ],
  "totalCount": 1
}

Code examples

volatility-spikes.js

const BASE             = "https://api.realmarketapi.com"
const API_KEY          = "YOUR_API_KEY"
const PERIOD           = 14
const SPIKE_MULTIPLIER = 2.0

const url = new URL("/api/v1/volatility/spikes", BASE)
url.searchParams.set("apiKey",          API_KEY)
url.searchParams.set("symbolCode",      "BTCUSD")
url.searchParams.set("timeFrame",       "H1")
url.searchParams.set("period",          String(PERIOD))
url.searchParams.set("spikeMultiplier", String(SPIKE_MULTIPLIER))

const res = await fetch(url.toString())
if (!res.ok) throw new Error("Request failed: " + res.status)

const { data, totalCount } = await res.json()
console.log(`Found ${totalCount} spike candle(s)`)
for (const spike of data) {
  console.log(spike.openTime, spike.direction, "×" + spike.multiplierReached)
}

▶️

Try it live in the Playground

Run a live /api/v1/volatility/spikes request with your API key — see the real response instantly in your browser.

Open Playground

GET

/api/v1/volatility/heatmap

Starter+

Aggregates the true range of all available candles into a Day-of-Week × Hour-of-Day grid. Each cell shows the average true range and a 0–1 normalised intensity for that time bucket, making it easy to identify when a symbol is typically most volatile. Uses all available historical candles — the more history on your plan, the more reliable the heatmap.

🗓️Results are sorted by dayOfWeek then hour ascending. Buckets with no candles are omitted. An intensity of 1.0000 marks the single most volatile time slot across the entire dataset.

Query Parameters

Name	Type	Description
apiKey*	string	Your API key.
symbolCode*	string	Symbol identifier (e.g. XAUUSD, BTCUSD).
timeFrame*	string	Candle interval: M1 · M5 · M15 · H1 · H4 · D1.

Response Fields — 200 OK

Field	Type	Description
dayOfWeek	string	Day name ("Monday" … "Sunday").
hour	integer	Hour of day in UTC (0–23).
avgRange	decimal	Mean true range across all candles that fell in this time bucket.
intensity	decimal	avgRange ÷ max(avgRange) across all buckets — 1.0 marks the most volatile slot.

Request

GET /api/v1/volatility/heatmap

GEThttps://api.realmarketapi.com/api/v1/volatility/heatmap?apiKey=YOUR_API_KEY&symbolCode=XAUUSD&timeFrame=H1

Response — 200 OK

response.json

{
  "data": [
    {
      "dayOfWeek": "Monday",
      "hour": 9,
      "avgRange": 812.340000,
      "intensity": 0.6714
    },
    {
      "dayOfWeek": "Monday",
      "hour": 14,
      "avgRange": 1209.110000,
      "intensity": 1.0000
    }
  ],
  "totalCount": 2
}

Code examples

volatility-heatmap.js

const BASE    = "https://api.realmarketapi.com"
const API_KEY = "YOUR_API_KEY"

const url = new URL("/api/v1/volatility/heatmap", BASE)
url.searchParams.set("apiKey",     API_KEY)
url.searchParams.set("symbolCode", "XAUUSD")
url.searchParams.set("timeFrame",  "H1")

const res = await fetch(url.toString())
if (!res.ok) throw new Error("Request failed: " + res.status)

const { data } = await res.json()
// Print the top-3 most volatile time slots
const sorted = [...data].sort((a, b) => b.intensity - a.intensity).slice(0, 3)
for (const slot of sorted) {
  console.log(`${slot.dayOfWeek} ${String(slot.hour).padStart(2, "0")}:00 — intensity ${slot.intensity}`)
}

▶️

Try it live in the Playground

Run a live /api/v1/volatility/heatmap request with your API key — see the real response instantly in your browser.

Open Playground

Error Codes

Common Error Codes

Code	HTTP	Description
ERR_0001_DATA_NOT_FOUND	400	No market data available for the requested symbol / timeframe
ERR_0005_INVALID_API_KEY	400	API key is missing, inactive, or not found
ERR_0007_INVALID_TIME_FRAME	400	Requested timeframe is not available on your plan
ERR_0008_SYMBOL_NOT_SUPPORTED	400	Requested symbol is not available on your plan
ERR_0012_EMAIL_NOT_VERIFIED	400	Account email has not been verified
ERR_0014_INVALID_PLAN	400	Free plan is not permitted to access this endpoint
ERR_0017_REQUEST_QUOTA_EXCEEDED	429	Monthly request quota has been reached

Name

Type

Description

apiKey*

string

Your API key.

symbolCode*

string

Symbol identifier (e.g. BTCUSD, XAUUSD).

timeFrame*

string

Candle interval: M1 · M5 · M15 · H1 · H4 · D1.

period

integer

Lookback window for ATR, Band Width, and Historical Volatility. Range 2–500. Default: 14.

Field

Type

Description

openTime

DateTimeOffset

Candle open timestamp (UTC).

atr

decimal

Average True Range — Wilder smoothed over period candles.

atrPercent

decimal

ATR as a percentage of closing price: ATR ÷ Close × 100.

bandWidth

decimal

Bollinger Band Width: (Upper − Lower) ÷ Middle × 100 — proxy for price expansion.

historicalVolatility

decimal

Rolling std dev of log returns over period candles, expressed as a percentage.

{ "data": [ { "openTime": "2025-06-01T08:00:00+00:00", "atr": 1234.560000, "atrPercent": 1.8432, "bandWidth": 7.2418, "historicalVolatility": 0.9751 } ], "totalCount": 1 }

const BASE = "https://api.realmarketapi.com" const API_KEY = "YOUR_API_KEY" const PERIOD = 14 const url = new URL("/api/v1/volatility", BASE) url.searchParams.set("apiKey", API_KEY) url.searchParams.set("symbolCode", "BTCUSD") url.searchParams.set("timeFrame", "H1") url.searchParams.set("period", String(PERIOD)) const res = await fetch(url.toString()) if (!res.ok) throw new Error("Request failed: " + res.status) const { data } = await res.json() for (const point of data) { console.log(point.openTime, "ATR:", point.atr, "HV:", point.historicalVolatility) }

Name

Type

Description

apiKey*

string

Your API key.

symbolCode*

string

Symbol identifier (e.g. BTCUSD, XAUUSD).

timeFrame*

string

Candle interval: M1 · M5 · M15 · H1 · H4 · D1.

period

integer

ATR lookback period. Range 2–500. Default: 14.

spikeMultiplier

decimal

Minimum ratio of candle ATR to series average ATR required to classify as a spike. Range 1.1–10.0. Default: 2.0.

Field

Type

Description

openTime

DateTimeOffset

Candle open timestamp (UTC).

atr

decimal

ATR value at the spike candle.

atrAverage

decimal

Mean ATR across the entire series used for comparison.

multiplierReached

decimal

atr ÷ atrAverage — how many times above average the spike was.

direction

string

Candle direction: "Bullish", "Bearish", or "Neutral".

{ "data": [ { "openTime": "2025-05-12T14:00:00+00:00", "atr": 3512.880000, "atrAverage": 1204.320000, "multiplierReached": 2.92, "direction": "Bearish" } ], "totalCount": 1 }

const BASE = "https://api.realmarketapi.com" const API_KEY = "YOUR_API_KEY" const PERIOD = 14 const SPIKE_MULTIPLIER = 2.0 const url = new URL("/api/v1/volatility/spikes", BASE) url.searchParams.set("apiKey", API_KEY) url.searchParams.set("symbolCode", "BTCUSD") url.searchParams.set("timeFrame", "H1") url.searchParams.set("period", String(PERIOD)) url.searchParams.set("spikeMultiplier", String(SPIKE_MULTIPLIER)) const res = await fetch(url.toString()) if (!res.ok) throw new Error("Request failed: " + res.status) const { data, totalCount } = await res.json() console.log(`Found ${totalCount} spike candle(s)`) for (const spike of data) { console.log(spike.openTime, spike.direction, "×" + spike.multiplierReached) }

Name

Type

Description

apiKey*

string

Your API key.

symbolCode*

string

Symbol identifier (e.g. XAUUSD, BTCUSD).

timeFrame*

string

Candle interval: M1 · M5 · M15 · H1 · H4 · D1.

Field

Type

Description

dayOfWeek

string

Day name ("Monday" … "Sunday").

hour

integer

Hour of day in UTC (0–23).

avgRange

decimal

Mean true range across all candles that fell in this time bucket.

intensity

decimal

avgRange ÷ max(avgRange) across all buckets — 1.0 marks the most volatile slot.

{ "data": [ { "dayOfWeek": "Monday", "hour": 9, "avgRange": 812.340000, "intensity": 0.6714 }, { "dayOfWeek": "Monday", "hour": 14, "avgRange": 1209.110000, "intensity": 1.0000 } ], "totalCount": 2 }

const BASE = "https://api.realmarketapi.com" const API_KEY = "YOUR_API_KEY" const url = new URL("/api/v1/volatility/heatmap", BASE) url.searchParams.set("apiKey", API_KEY) url.searchParams.set("symbolCode", "XAUUSD") url.searchParams.set("timeFrame", "H1") const res = await fetch(url.toString()) if (!res.ok) throw new Error("Request failed: " + res.status) const { data } = await res.json() // Print the top-3 most volatile time slots const sorted = [...data].sort((a, b) => b.intensity - a.intensity).slice(0, 3) for (const slot of sorted) { console.log(`${slot.dayOfWeek} ${String(slot.hour).padStart(2, "0")}:00 — intensity ${slot.intensity}`) }

Error Codes

Common Error Codes

Code	HTTP	Description
ERR_0001_DATA_NOT_FOUND	400	No market data available for the requested symbol / timeframe
ERR_0005_INVALID_API_KEY	400	API key is missing, inactive, or not found
ERR_0007_INVALID_TIME_FRAME	400	Requested timeframe is not available on your plan
ERR_0008_SYMBOL_NOT_SUPPORTED	400	Requested symbol is not available on your plan
ERR_0012_EMAIL_NOT_VERIFIED	400	Account email has not been verified
ERR_0014_INVALID_PLAN	400	Free plan is not permitted to access this endpoint
ERR_0017_REQUEST_QUOTA_EXCEEDED	429	Monthly request quota has been reached