DEVELOPERS

The market data API that lets you ship a product on it.

Liquidation heatmaps, funding and open interest, AI-scored news with impact ratings, fear and greed, geo hotzones and tracked trade signals. Commercial use is allowed on every tier, including free, and pro keys get the full TimescaleDB history instead of a three-month window.

GET A FREE KEY USAGE MONITOR PRICING

GET STARTED IN 3 STEPS

CREATE A KEY

Sign in and mint a key on the API keys page. A free account includes one key, no card required. The full secret is shown exactly once, so copy it right away.

vk_live_................................

MAKE YOUR FIRST REQUEST

Every endpoint is a read-only GET under /api/public/v1. Authenticate with the X-API-Key header, or ?api_key= from a browser.

Full examples below the fold.

READ YOUR LIMITS

Call /meta to see your tier, limits and usage today, and watch the X-RateLimit-* headers on every response. The usage monitor shows the same live, per key.

curl -H "X-API-Key: vk_live_YOUR_KEY" \
  "https://api.forecandle.com/api/public/v1/candles?symbol=BTC&tf=1h&limit=100"

FREE VS PRO

FREE KEYPRO KEY

API keys per account15

Requests per minute60300

Candle history30 daysFull history

Events history7 daysFull history

Liq-heatmap history24 h48 h

SignalsMulti-day embargo · closed in fullReal-time, full levels

Commercial useYes, with attributionYes

A key's tier follows its owner's plan: upgrade and every key you own becomes a pro key instantly. Free-tier consumers must show "Data by Forecandle" with a link. Comparable products forbid commercial use below $299/month; here it is allowed on the free tier.

RATE LIMITS

Each key gets a fixed per-minute window: 60 requests on free, 300 on pro. Every response, success or error, reports where you stand in four headers. When the window is spent you get a 429; wait for Retry-After seconds (at most 60) and the counter starts fresh.

HEADERMEANINGEXAMPLE

X-RateLimit-LimitRequests allowed per minute for your tier.60

X-RateLimit-RemainingRequests left in the current minute window.42

X-RateLimit-ResetUnix seconds when the window rolls over.1784889600

Retry-AfterSeconds to wait. Sent only with a 429.21

Live per-key usage, today's totals and a 14-day history are on the usage monitor.

ERRORS

Every error is one JSON envelope: a stable machine code plus a human explanation.

HTTP 403
{"error": "forbidden",
 "detail": "pro key required for >30d candle history (free keys look back 30 days)"}

401unauthorizedmissing, unknown or revoked key

403forbiddentier depth gate (e.g. free key asking beyond 30d) or key cap

404not_foundunknown symbol or resource

422invalid_requestbad parameters (message names the field)

429rate_limitedover the per-minute limit, Retry-After set

ENDPOINT REFERENCE

10 ENDPOINTS · ALL GET

Click a row to expand params, gating and a copyable request/response pair. Base URL: https://api.forecandle.com/api/public/v1

CHECK YOURSELF ANYTIME

curl -i -H "X-API-Key: vk_live_YOUR_KEY" "https://api.forecandle.com/api/public/v1/meta"

HTTP/1.1 200 OK
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 59
X-RateLimit-Reset: 1784889600

{"key": {...}, "limits": {...}, "usage_today": {"requests": 12}, "rate": {...}}

GO PRO

Pro unlocks 5 keys, 300 requests per minute, full TimescaleDB history on candles and events, and the 48-hour heatmap matrix. The measured event-reaction ledger behind /calibration is public on every tier, including no tier at all.

SEE PRICING

TERMS OF USE, AND WHAT YOU MUST PASS ON

Forecandle publishes impersonal market data, scored news and model output. It is not financial, investment or trading advice, not a personal recommendation, and not an offer or solicitation to buy or sell anything. Nothing published takes account of any individual's circumstances, objectives or risk tolerance. Signal entry, target and stop levels are illustrative parameters of a hypothetical trade, not instructions and not orders, and no capital is deployed behind them. Any performance figure is the measured history of a published model's calls, excludes fees, funding and slippage, and does not predict future results. Trading carries a high risk of losing all of your capital and leveraged products amplify that risk. You alone are responsible for your own decisions.

Every response carries this text in a disclaimer field and on the X-Forecandle-Disclaimer response header. If you display Forecandle data to end users you must display that notice with it, and free-tier keys must attribute Forecandle with a link. Redistributing signal levels without the notice is a breach of the Terms. See the Risk Disclosure for what the levels are and are not.

READ-ONLY MARKET DATA · AI ANALYSIS · NOT FINANCIAL ADVICE