API reference

One endpoint does most of the work: POST /api/v1/chart. Send a pair and a timeframe; get back structure, levels, concepts, a plan and, if you ask, a top-down read. The API is in private preview.

Authentication /v1/chart Concepts Credits and limits Errors /v1/structures Examples

Authentication

Create a key in your API console. Send it on every request as Authorization: Bearer fxs_live_... or X-API-Key: fxs_live_.... A key is shown once; we store only its hash. Up to three active keys per account; revoke one in the console and it stops working at once. Keep keys on your server, never in a browser or app.

POST /api/v1/chart

Request body (JSON):

symbol

string, required

The instrument, as you know it: EURUSD, XAUUSD, GOLD, US30, NAS100. Common aliases are matched to the name our price source uses; the answer tells you which one it used.

timeframe

string, required

One of M1, M5, M15, M30, H1, H4, D1, W1.

bars

number, optional

How many recent bars to measure, 30 to 500. Default 200.

concepts

array or "all", optional

Concept ids from the list below, or "all". Included in the call's credit.

top_down

boolean, optional

Also read every higher timeframe at the same moment. 1 extra credit per timeframe read.

Response fields:

symbol / requested

The instrument measured, and what you asked for.

timeframe, digits, bars

What was measured and at what precision.

lastBar

{ time, close } of the latest completed bar. time is epoch seconds (UTC).

feedLive, stale

Whether prices are live and whether the latest bar is older than expected (weekends, holidays).

marketStructure

"uptrend", "downtrend" or a range reading, from the swing walk.

levels

Up to 12 support and resistance bands, strongest first: { low, high, rejections }.

orderBlocks

Order blocks with type (bullish_ob / bearish_ob), top, bottom and the bar they formed on.

fvgs

Fair value gaps with type, top, bottom, the bar they formed on and, once filled, the bar that filled them.

swings, breaks, sweeps, equalLevels

Swing highs and lows, breaks of structure and changes of character, liquidity sweeps, equal highs and lows.

plan

The engine's rule-based plan: side, entry, stop and targets when there is a directional read, or ok: false with a plain refusal.

concepts

Per requested concept: { label, found, note, marks[] }. Each mark has a kind (line, band, box, point), a label, price or top and bottom, and bar indices (atBar, fromBar, toBar).

topDown

Per higher timeframe, largest first: { timeframe, bias, zone, rangePosition, levelAbove, levelBelow, last }.

usage.units

Credits this call used.

meta

How to read indices and prices, and the note that this is tool output, not advice.

Bar indices are 0-based into the bars this call measured, oldest first. Prices are absolute, at the instrument's own precision. The same bars always give the same answer.

Concepts

Order blocks, fair value gaps, swings, breaks, sweeps and equal levels come on every call. These are added on request by id:

sessionsSessions

Asian, London and New York ranges, in UTC.

killzonesKill zones

The windows ICT calls kill zones: the two opens, the London close, the silver bullet hour.

openingRangeOpening range

The first half hour of New York, and the bar that first closed outside it.

powerOfThreePower of three

Accumulate, manipulate, distribute: only marked where all three actually happened.

sessionOpensDay / week / month open

The opening price of the current day, week and month.

crtCRT

One candle's range, swept by the next, which closes back inside it.

premiumDiscountPremium / discount

The dealing range, its midpoint, and the 62-79% optimal entry band.

breakersBreaker blocks

An order block price broke through, which then works the other way.

inverseFvgInverse FVG

A gap traded through, now acting as opposition rather than support.

rejectionRejection blocks

A long wick into a level that price then turned away from.

liquidityBuyside / sellside

Where stops rest: equal highs above, equal lows below.

turtleSoupTurtle soup

A new 20-bar extreme that closed straight back inside: a failed break.

judasJudas swing

The early move that swept a level and then reversed for the rest of the day.

supplyDemandSupply & demand

A tight base followed by a hard departure. Not the same thing as an order block.

displacementDisplacement

The impulsive move that makes a structure break mean something.

rangesRanges

Compression and expansion. A compression is closed at the bar that broke it.

voidsLiquidity voids

Ground covered in one move with little overlap, which price tends to revisit.

roundNumbersRound numbers

The prices everyone watches, with how often price has touched each.

vwapVWAP

Volume-weighted average price for the day, with one standard deviation either side.

emasMoving averages

The 20, 50 and 200 EMAs, and where price sits against them.

rsiDivRSI divergence

Price made a new extreme, momentum did not follow.

volumeProfileVolume profile

Where the market accepted price: the opposite question to where it rejected it.

Credits and limits

1 credit per chart call. Concepts are included.
With top_down, 1 more credit per higher timeframe read (an H1 chart reads H4, D1 and W1: 3 more).
Failed calls, and pairs we do not carry, use nothing.
Rate limit by plan: Starter 30, Growth 60, Scale 120 requests a minute.
Plans: Starter $29 a month (1,000 credits), Growth $99 (5,000), Scale $399 (25,000). Plan credits reset every billing month.
Top-up: 1,000 credits for $40. Top-up credits never expire and are used after the plan's. See pricing.
Each response carries usage: units used, plan credits left and top-up credits left.

Errors

Every error has a JSON body with an error message you can show.

400

Missing or wrong symbol or timeframe.

401

No key, a malformed key, a wrong key or a revoked key.

402

No active API plan on this account, or not enough credits for the call (the body says how many are left). Nothing is charged.

404

We do not carry that instrument. Nothing is charged.

422

Too little history for that instrument and timeframe.

429

Too many requests. The body carries resetAt; retry after it.

503

Prices unavailable for a moment, or your access is not switched on yet during the preview. Nothing is charged.

500

The engine could not finish. Nothing is charged; retry.

POST /api/v1/structures (bring your own bars)

Already have the bars, from your own platform or broker? Send them as { symbol, timeframe, bars: [{ time, open, high, low, close }] }, 20 to 1,000 bars, oldest first, and get back the same structure fields, addressed by 1-based bar index into what you sent. Useful when you must use your own prices.

Examples

curl

curl -X POST https://fxsynapseai.com/api/v1/chart \
  -H "Authorization: Bearer $FXS_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "symbol": "EURUSD", "timeframe": "H1", "bars": 200,
        "concepts": ["crt", "killzones"], "top_down": true }'

JavaScript

const res = await fetch("https://fxsynapseai.com/api/v1/chart", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.FXS_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ symbol: "XAUUSD", timeframe: "M15", concepts: "all" }),
});
if (!res.ok) throw new Error((await res.json()).error);
const chart = await res.json();
console.log(chart.marketStructure, chart.levels[0], chart.plan);

Python

import os, requests

r = requests.post(
    "https://fxsynapseai.com/api/v1/chart",
    headers={"Authorization": f"Bearer {os.environ['FXS_KEY']}"},
    json={"symbol": "GBPUSD", "timeframe": "H4", "top_down": True},
    timeout=30,
)
r.raise_for_status()
chart = r.json()
print(chart["marketStructure"], [t["bias"] for t in chart.get("topDown", [])])

What the API returns is tool output measured from prices: structure, levels and a rule-based plan. It is not financial advice and makes no claim about future results. Questions: support@fxsynapseai.com.