One envelope, every route

Market data routes are namespaced by market type: /api/spot/… and /api/futures/…. Everything else health, configuration, subscriptions, the event log is global, because a subscription rule carries its own market type and would be contradicted by a second one in the path.

Nothing is tracked until you ask. An idle engine holds a pair catalogue and no streams. Favorite a pair and the engine opens what it needs for that pair; remove it and the streams close. Chart and OHLCV routes are the two exceptions they work on any catalogued pair, favorited or not, because both can backfill.

The engine computes, it does not only relay. Indicators, derived market structure, orderflow metrics, strategy documents, backtests, a trade journal and scored market events are all first-class parts of this API, grouped into 5 feature modules. Which of them a build carries is reported by the capabilities route, so a client discovers the surface instead of assuming it.

One route sits outside the scope system entirely. GET /api/agent/capabilities answers however far a caller has narrowed itself, because an agent that has just been handed a smaller grant needs a way to learn what that grant is without discovering it one 403 at a time.

The answer describes the whole vocabulary and this caller’s place in it: which capabilities exist and what each is for, which of them this request holds, which need confirmation and how to send it, which socket channels and operations the same rules apply to, where narrowing can be applied, and which feature modules this build actually carries. Send it with a narrowing header and it answers for the narrowed caller, which makes it the cheapest way to test a header before you rely on it.

Responses are application/json; charset=utf-8 and Cache-Control: no-store. Protocol-level failures use the envelope too, so a client never has to parse two shapes.

One route answers outside it. The chart route can return raw PNG bytes — ?raw=1, or an Accept header that ranks image/png above JSON. That selects the shape of a success only: a failure is still an envelope. Curl’s default Accept: */* ties and loses, so a plain curl gets the envelope.

OPTIONS on any path answers the preflight for GET, POST, PATCH, DELETE, OPTIONS. PATCH is on the list because the subscription enable/disable route uses it, and a verb missing from a preflight is a verb a browser will not send.

The same answer advertises every request header the engine accepts — Content-Type and X-Engine-Token for the transport, then X-PS-Scopes and X-PS-Confirmed for the authorization layer. A header a preflight does not advertise is a header a browser will strip before you ever see the failure.

The table above is the engine’s own frozen set, written in lower snake case. The five feature modules add their own codes alongside it, and those are written in upper snake case — STRATEGY_NOT_FOUND, BACKTEST_JOB_NOT_FOUND, CUSTOM_INDICATOR_INVALID and so on. The convention is deliberate: the case of a code tells you whether the core dispatcher or a module refused you, before you have read the message.

A module refusal may also carry more than the two envelope fields. A validation failure attaches error.errors[] every problem at once, each with the path in your document that caused it and some refusals attach error.data with the detail a client needs to recover, such as which strategy still references the indicator you tried to delete. Both are additions to the failure envelope, never replacements for it, so a client that only reads the code keeps working.

The chart route and the OHLCV route are the two that work on a pair you have not favorited: both can backfill from the exchange. A tracked pair is drawn straight from memory instead.

Context routes serve favorited pairs only, and a pair that has just been favorited answers thinly for the first seconds while it warms up. A 404 on a context route usually means one of those two things rather than a wrong URL.

/klines works on any catalogued pair. The other four serve favorited pairs only there is no recorded book or footprint for a pair nobody asked the engine to watch.

Order state is canonicalised across the eight venues, so one status vocabulary works everywhere and you do not write a per-exchange adapter. Credentials are never part of a record.

Three of the four routes touch no network at all they read records this engine already holds, so a status is only as fresh as the last thing it heard. Only /orders/refresh reaches a venue, and it is the one that resolves a stale status. A record exists because the order went through this engine: orders placed directly at the exchange are not visible here.

The two reads need orders.read. The two writes need orders.write and the confirmation header on top of it. Neither of them places an order, and both were still put behind the gate on purpose: one destroys the record you would reconcile against, and the other spends your credentials and rewrites what the engine believes.

The catalogue ships with 33 built-in indicators across 7 categories. Anything you write joins the same catalogue under the custom category and is thereafter indistinguishable from a built-in: it lists, it computes by id, and a strategy can refer to it.

One request computes up to forty entries over a single pair and returns them on one shared axis, so a consumer never lines two series up by hand. Each entry names an id, optional key to control what the output is called back, optional params to override the indicator’s own defaults, and optionally a timeframe of its own.

That per-entry timeframe may be HIGHER than the request’s own, and this is the part worth understanding before you rely on it. The value at each bar is the last higher-timeframe bar that had already closed by that point never a value from the future and the answer records the bar at which the alignment became valid, so you can drop the warm-up window yourself instead of guessing at it. A LOWER timeframe is refused outright: there is no honest way to spread one bar across many.

One GET returns the structural analysis of a timeframe: every structural read for that horizon, in one answer. The sensitivity is yours to set the pivot arms either side of a swing, the lookback, the ATR multiple and period, and how far apart two prices may be and still count as equal.

The same idea computed from the live book rather than from bars, over the depth you choose. A metric that cannot honestly be computed at this moment comes back declared unavailable with the reason attached. It is never a silent zero, because a zero is a number a strategy will happily trade on.

A definition carries an id, a name, at most eight params and between one and eight outputs. Leave the id out and it is derived from the name; every id is prefixed, so a custom indicator can never collide with a built-in one.

A param declares its type integer, number, enum or boolean a default, and the bounds or options it will accept. An output declares its formula plus how it should be drawn: which kind of mark, which pane it belongs in, what it is anchored to, and which side it argues for.

Outputs evaluate in the order they are declared and may read the outputs declared before them. Referring forward is a cycle, and a cycle is refused rather than resolved.

A formula is never evaluated as JavaScript, so a definition is data you stored and not code you are running. Three invariants follow from that, and all three are worth designing around.

Bar fields, series functions and callable built-ins are three different things, and the guide route enumerates all three for the version you are running. One trap is worth stating here, because it catches almost everyone: sma, ema, wma and atr are series functions and take the series first. Write ema(close, 20) and not ema(20). A custom indicator also cannot call another custom indicator.

Four steps in that order, and each exists to make the next one cheap. Read the guide for the grammar this engine will actually parse. Validate to get every problem at once, each with the path that caused it. Preview over a favorited pair to see real numbers before anything is stored. Then create.

An indicator that a saved strategy still refers to cannot be deleted the refusal is CUSTOM_INDICATOR_IN_USE, and it names what is holding the reference. Change the strategy first. Stored definitions survive a restart; there is no version history behind them, because the version is a counter and not a log.

A definition names the market it was written for platform, market type, symbol and timeframe then declares its inputs, the conditions that open a position long or short, the filters that may veto one, the exit, and a risk block: how size is chosen, how many positions may be open at once, the daily loss that stops trading, the least reward-to-risk worth taking, and the conditions to sit the session out entirely.

None of it is free text the engine has to interpret. Validation resolves every indicator the document refers to, reports how many bars it needs before it can produce a first signal, and hands back the normalised document it would actually have stored so what you review is what would run.

Every write makes a new version, and the old one stays readable. A refinement is expressed as a list of operations — set, unset, push, remove against a dotted path rather than as a whole replacement document, so the record of what changed is the change itself and not a reconstruction made afterwards. The new version records the version it came from, the fields the edit touched, and a summary of it.

Two versions can be diffed, and any version can be explained in prose. A draft that was never stored can be validated and explained too, which is what makes an author-then-check loop cheap: nothing is written until the document is worth keeping.

The whole schema is large enough to be unhelpful as a single answer, so it is served in sections and defaults to the overview. Ask for the section you are currently writing.

A create returns a job id and a queued status, and nothing else. Poll the job, or subscribe to the backtest channel on the socket and be told. The report arrives attached to the job once its status is done.

The two DELETEs are different verbs wearing the same word, and the distinction matters.

Exactly one code means the job is gone — 404 BACKTEST_JOB_NOT_FOUND. Everything else is a job you can still ask about, which is what lets a client distinguish "removed" from "not ready", "cancelled" and "failed" without guessing. A job whose report is no longer available still answers, and says so, rather than pretending it never had one.

Three of the five are terminal: done, failed and cancelled. A job in any of them will never move again.

An entry is one trade: where it happened, which way you were positioned, when you got in and out and at what price, what it cost, what you had planned, how you file it, and what you made of it afterwards.

Two things about it are fixed rather than editable, and both are deliberate. Identity facts symbol, direction, entry time, entry price and size cannot be patched: an entry whose entry price can be edited afterwards is not a record of anything. If one of them is wrong, delete the entry and write it again. And attachments carry a reference only, never bytes; the journal stores where a chart or an image is, not the file itself.

A captured entry is derived automatically from the engine’s own order-update stream, idempotently, so the same fill cannot produce two entries however many times it is seen. A manual entry is for a trade placed somewhere this engine never saw. The two are distinguished by origin so that you can tell them apart later and so that you do not quietly duplicate a captured trade by writing it out again by hand.

PnL is computed rather than accepted: for a long, exit minus entry times size, less fees; for a short, the same with the sides swapped. The percentage is against the entry notional. R multiple needs a planned stop on the correct side of the entry without one there is no R, and the engine reports its absence rather than inventing a denominator.

Statistics carry a behaviour block alongside the performance one, so a review covers how you traded and not only what it returned. The calendar files a trade on the day it CLOSED, in UTC unless you send an offset with the request.

An import is all-or-nothing. One malformed entry in a file of four hundred rejects the whole file and tells you which ones were wrong, because a half-imported journal is worse than an unimported one you cannot tell what is missing.

There are 16 types. They fall into three rough families: something large happened in the tape, something changed in the book, or the structure of the market itself moved. Filter by any combination of them, or take the lot and filter on score.

Every event carries a score from 0 to 100. Filter on it directly when you want a hard floor, rather than inferring importance from the type alone.

Urgency is a band over that score rather than a separate judgement, and both thresholds are published on the types route so that a client never hardcodes them. The three bands are:

An event says what happened, where it happened, how strongly it scored and which urgency band that score falls in. Nothing in it is a projection.

The same thing happening again at the same price is not a new event. It is re-scored, its repetition count moves, and it is re-emitted as an update to the event you already have. A consumer that keys on the event id therefore gets one row that gets more urgent, rather than forty rows that each look like news.

enabled is the only mutable field. Changing a rule, a URL or a trigger control means delete and create a rule that quietly became a different rule is a rule you cannot reason about. Disabling drops it out of evaluation immediately and preserves every counter; enabling puts it back with a clean trigger state, because a sample taken before an unknown gap would otherwise fabricate a crossing.

/test sends one signed delivery right now and reports how the round trip went. It succeeds even when the delivery fails a refused connection comes back as an unsuccessful result, not as an error so read the result rather than the absence of an error. Use it to prove your endpoint is reachable and that your signature check works before you rely on a rule.

<path> addresses a value inside the pair’s published context. Read one compiled context to see exactly which paths a pair currently exposes, then write the dotted route to the value you care about. Paths are case-sensitive.

The timeframe field is always required, because it is what routes the rule into the evaluation index even for a path whose value is not per-timeframe. Whitespace around a symbol operator is optional; the four word operators must be whitespace-delimited.

The body is JSON describing the subscription that fired and the value that fired it. The signature covers the exact bytes on the wire verify before you parse, never after a re-stringify, or a difference in key order or whitespace will fail a signature that was perfectly valid.

Delivery retries with backoff on network errors, 429 and 5xx. A subscription whose endpoint keeps failing terminally is auto-disabled rather than left to hammer a dead host; the record says so, and enabling it again resets the failure state.

The response carries the events, the cursor to pass on your next call, and the oldest cursor still retained. If the oldest retained cursor is greater than the one you asked for, the log has rolled and you missed events which is a thing you can detect and act on, rather than a silence you have to guess at.

The log is independent of the subscriptions themselves: entries written by a subscription that has since been deleted are still replayed.