so.blackforge/mcp

Get notified when a saved live formula crosses a value you set. It is evaluated server-side every interval, whether or not anything is connected. direction: above (goes from at or below the threshold to above it), below (the reverse), or cross (either). After it fires it waits until the value is back on the other side by at least hysteresis and cooldownSeconds (60 to 86400, default 900) have passed. If the condition is already true when created, it starts disarmed and arms once the value is back across. It never fires on null or on a WARMING or stale value. Email goes to the account's verified address (default on); webhookUrl (https) optionally receives a signed POST. The response carries webhookSecret ONCE: store it to verify the x-blackforge-signature header (t=<unix>,v1=<hex HMAC-SHA256 of t.body>). Live formulas and notifications are part of the Ultra plan.

Delete a formula notification. The formula itself is kept. Cannot be undone.

List the account's formula notifications ({ alerts, limits }). Each carries its formula, direction, threshold, status (active, paused, quota, plan), whether it is armed, and when it last fired. Live formulas and notifications are part of the Ultra plan.

Read the live order book for one pair right now: the top levels on both sides as [price, quantity] pairs, when it was read (observedAtMs), whether the book is synced or crossed, and level counts. levels is 1 to 200, default 20. Charged 2 rows per level returned. Live order book reads need the Max or Ultra plan and are charged against the monthly row quota.

List every venue BlackForge covers (9 spot exchanges) and every column it measures (one wide row per (exchange, symbol) per minute, served at 1m, 5m, 1h and 1d: order-book depth and shape, resting-liquidity lifetimes, trade-explained vs book-implied volume, spreads, and market-wide context). `metricCount` is the exact number of columns available now. Each metric carries a precise measurement definition, unit, family, and the minimum plan that includes it, the `intervals` it is served at, and, where the 5m/1h/1d value is a rollup of minute values rather than a re-measurement, a one-sentence `rollupNote`. `availableFrom["1m"]` is when the one-minute rows start (null before). `availableFrom.bookOnBoundary` maps each venue to the first window end whose order book was read as it stood at that instant (such rows have `bookObservedAt` equal to `ts`, so venues line up), null before; the order book columns carry a one-sentence `bookTimingNote` on it. The `qualityFlags` metric also carries the `bits` table that decodes the per-row quality mask. This route needs no API key. CALL THIS FIRST to learn the exact `exchange` and `metric` identifiers the other tools accept.

Walk the live order book to price a market order of a given size right now, without placing anything. Give usd (notional in USD) or size (base quantity). Returns { complete, bps, partialBps, levelsWalked, vwap, depthLimited, bookExhausted }: bps is the cost against the mid in basis points and is null unless the visible book could fill the whole order (then see partialBps, and do not quote it as the cost). Charged one row per level walked. Live order book reads need the Max or Ultra plan and are charged against the monthly row quota.

Save a live formula to the account so it can be streamed (blackforge_formula_watch) and carry notifications (blackforge_alert_create). Returns { formula: { id, name, expr, interval, pairs, horizonSeconds, ... } }. A refused formula comes back as an error with the same located, coded detail blackforge_formula_validate gives; validate first. Saving is free; a formula is charged one row per referenced pair per evaluation only while it is streamed or watched by a notification. Live formulas and notifications are part of the Ultra plan.

Delete a saved live formula. Its notifications are deleted with it and listed in deletedAlerts. Cannot be undone.

List the account's saved live formulas, with the plan's limits and current usage ({ formulas, limits, usage: { live, stored, connections } }). Live formulas and notifications are part of the Ultra plan.

Check a live formula without saving it. Free and unmetered, so iterate on it freely. On success returns { ok: true, normalised, pairs, primitives, horizonSeconds, cost: { rowsPerEvaluation, rowsPer30Days } }. On a refusal returns { ok: false, error } where error carries a stable code, a message, the location (at, pointer under the source) and suggestions such as the correct pair spelling: apply them and check again. A formula is an arithmetic expression over live order book and trade data, evaluated server-side every interval (default 1 s). Pairs are written venue:SYMBOL exactly as blackforge_symbols spells them (binance:BTCUSDT, okx:BTC-USDT, coinbase:BTC-USD), and one formula may combine pairs on different venues. Durations are 1s to 60s, or 1m. Book state, read now: bid ask bidQty askQty mid spread spreadBps bidLevels askLevels quoteUsd last lastAge, each (pair). Book walk: bidDepth askDepth imbalance (pair, bps) with bps an integer 1 to 200 written as a number; buyCost sellCost (pair, usd) with usd 100 to 1000000, result in bps. Trades over a window: buyVol sellVol vol buyUsd sellUsd volUsd buyCount sellCount tradeCount netFlow buyShare vwap high low open close maxBuy maxSell (pair, duration); buyUsdAbove sellUsdAbove buyCountAbove sellCountAbove (pair, duration, usd) with usd one of 100, 1000, 10000, 100000. Book changes over a window: bidAdded askAdded bidRemoved askRemoved bidAddedNear askAddedNear bidRemovedNear askRemovedNear bookChanges (pair, duration). Scalar: abs sign sqrt ln log10 exp pow min max clamp round floor ceil if coalesce. Windows over any expression: avgOver minOver maxOver stdOver change pctChange (expr, duration). Operators + - * / ^, comparisons, and, or, not. A missing input gives null, never a made-up number. The sum of windows on any path (the horizon) is at most 60 s. Examples: mid(binance:BTCUSDT) - mid(okx:BTC-USDT); imbalance(binance:ETHUSDT, 50); buyVol(binance:SOLUSDT, 60s) / max(sellVol(binance:SOLUSDT, 60s), 1); avgOver(spreadB…

Stream a live formula for a few seconds and return what arrived: first, last, min, max, the number of samples, which value flags appeared (with a plain note for each), and the full series of { ts, value, flags? } with ts in epoch milliseconds. Pass formulaId for a saved formula, or expr to watch a formula once (it is saved as a one-hour formula first). seconds is 1 to 60, default 20. A value flagged WARMING is computed over less than its full window, because the formula is younger than its horizon; it settles by warmUntil. null means there was no number (for example no print in a trade window), never zero. Charged one row per referenced pair per evaluation. Live formulas and notifications are part of the Ultra plan.

Return the latest completed bucket for one (exchange, symbol), at the key plan's interval (1 minute on Ultra and PAYG, 5 minutes otherwise): a `values` object mapping each column key to its measured number (or null when not observed), plus the window END timestamp `ts` in epoch milliseconds. Omit `columns` to get every column your plan includes; pass a subset of column keys (from blackforge_catalog) to narrow the payload. Columns your plan does not cover are dropped and reported in `columnsOmitted` so you can see why a key is absent. WHEN PRESENT, a `quality` object reports the row's measurement quality: `flags` names what went wrong during the window and `contaminates` lists which figures it flags, with a plain-English `qualityNote` beside it. Read it before trusting an unusual value. A `quality.raw` of 32768 means the row predates the quality rail and was never assessed; that is unknown, not bad. When the key is absent, the row carries no quality assessment at all.

Return a time series for one column of one (exchange, symbol): `points` is an ascending array of { ts, value } where `ts` is epoch milliseconds and `value` is the measured number (or null). `from`/`to` are ISO-8601 datetimes; `interval` is one of 1m, 5m, 1h, 1d. 1m is on Ultra and PAYG (PAYG bills a 1m row at five times a 5m row); Max and below go down to 5m, and a finer interval than the plan allows is a 403. 1m rows exist only from the switch to one-minute rows on (see blackforge_catalog `availableFrom`); for earlier ranges use 5m, which covers all history. The server caps a response at 50,000 points (about 34 days at 1m) and keeps the NEWEST; `truncated: true` says the range was cut, so narrow it or use a coarser interval. If the requested `metric` is above your plan, `points` comes back empty and the column is listed in `columnsOmitted`, which is why it is empty. WHEN ANY BUCKET IS FLAGGED, a `qualitySummary` object reports how many of the buckets carry a quality flag and which flags they are (`{ flaggedBuckets, of, flags }`); per-bucket quality is deliberately not repeated on every point. No `qualitySummary` means no bucket in the range was flagged.

Best bid and best ask for one base/quote pair on every venue that lists it, all read within the same moment, so a difference between venues is a real difference rather than a timing artefact. Charged 2 rows per venue. Live order book reads need the Max or Ultra plan and are charged against the monthly row quota.

List the trading pairs (symbols) a given venue trades, as an array of symbol strings. Use these values as the `symbol` argument to blackforge_latest and blackforge_series. Valid `exchange` values come from blackforge_catalog (e.g. binance, bybit, coinbase, kraken, okx). A venue outside the caller's plan returns HTTP 403 with the plan and an upgrade URL.

Report the calling key's recent usage: `days` is a per-day breakdown of request counts and the last request time, and `rowsRemaining` is the monthly row quota still available (omitted for usage-based plans that have no monthly ceiling). Use this to check headroom before a large pull.