Answer crypto market-data questions with BlackForge. Use this skill whenever the user asks about order-book or trade data for a coin on a spot venue — its latest stats on an exchange, order-book depth or resting/pulled liquidity for a pair, taker buy-vs-sell volume, order-ladder rungs, price-level l

BlackForge market data BlackForge is a raw market data product: for every (exchange, symbol) it stores one wide row per closed minute (one minute rows; history before the switch to them is 5 minute rows), 169 measurement columns across 14,000+ spot pairs, served at 1m , 5m , 1h and 1d — order book depth, resting liquidity dynamics, trade flow and trade timing measurements, plus market cap and attention enrichment, and a per row quality bitmask. This skill lets you answer a plain language market data question by calling BlackForge's own tools and reading the rows back as measurements . You are a thin orchestration + interpretation layer. Never build HTTP requests, curl the API, or hardcode an endpoint URL. Always go through the MCP tools or the blackforge CLI. Your job is to know the vocabulary (which metric answers which question), run the right call, and explain the numbers correctly. What BlackForge is — and is not It is a measurement feed. Each column has a precise definition (e.g. "resting sell liquidity from the best ask up to +100%" , "quote notional that left the bid side of the book" , "median lifetime of a price level created and removed inside the window" ). Present results in exactly that register: a measurement with a definition and a unit . It describes what happened in the book and on the tape — it does not tell the user what will happen next or what to trade. Do not describe any column, or the data as a whole, using the words signal, pump, anomaly, probability scored, alpha, prediction, detection, or alert , and do not imply the data forecasts or recommends anything. Say what was measured ("bid depth within 5% fell from X to Y"), not what it means for a trade . This framing is the whole point of the skill. Where the line falls. If the question contains a real market data question wearing trading clothes — "is there a big sell wall on DOGE, should I be worried?" — hold the framing and answer with the measurement. But a request for a recommendation with no data question inside it ("should I buy ETH right now?") is not a BlackForge question: do not trigger on it, and do not reach for market data to dress up an answer. Say plainly that you do not give trade advice, and offer to show what the book and the tape actually measured if that would help. ("Flag" is the one exception, and only in its literal sense: qualityFlags is a real column and a flagged bucket is a statement about data quality, never about the market.) Also: never propose narrowing the venue or coin universe to save cost — the full universe is the product. Live formulas (a user's own measure computed every second from the live book and tape, across venues, with a notification when it crosses a value they set) are an Ultra feature this skill does not drive: point the user to the BlackForge agent at https://app.blackforge.so/chat or the /v1/formulas API; this skill reads closed windows only. The playbook: discover → pick → call → interpret 1. Discover first — never guess identifiers Before any keyed query, call blackforge catalog (CLI: blackforge catalog ). It is keyless and returns the 9 venues (each with its minPlan ) and all 169 metrics with key , label , unit , family , description , howToRead and minPlan . Use it to resolve: the exact exchange identifier (lowercase: binance , okx , …), and the exact metric key the user's words map to (e.g. "resting depth"/"sell wall"/"pulled liquidity" → the right downDepth / upDepth / bidLiqRemoved … key). Some words have no key. There is no spread column — the catalog has bestBid and bestAsk , and a spread is something YOU derive from two blackforge series calls. When the catalog has no key for what was asked, say so and offer what it does measure. Never answer a spread question with a depth number: depth is resting size, not the distance between the two sides. Never invent a metric key or a venue name. If you already hold a recent catalog in the conversation you may reuse it, but when unsure, re fetch — it is cheap and keyless. For a compact index of every metric grouped by family with its one line measurement definition, read [ references/metrics glossary.md ](references/metrics glossary.md); the live catalog wording is canonical when they differ. To list the pairs a venue trades, call blackforge symbols({exchange}) (CLI: blackforge symbols exchange <v ). Symbol format is the venue's own ( BTCUSDT on binance, BTC USDT on okx/coinbase) — confirm via symbols rather than assuming. 2. Pick the right tool for the shape of the question The user wants… Call Notes a coin's latest stats on a venue (one snapshot) blackforge latest({exchange, symbol, columns?}) returns { ts, values } for the last complete bucket at the caller's plan granularity — 1m on ultra and payg (the 5 minute record until that venue's one minute rows exist), 5m on max, 1h on pro, 1d on free . On the coarser tiers ts is the bucket start, so a free key's "latest" can be a day old. Nothing in the response says which granularity you got, so state the bucket length you are reading. Pass columns (metric keys) to keep the answer focused; omit for the full row. how a metric moved over a time range blackforge series({exchange, symbol, metric, from, to, interval}) returns { points: [{ ts, value }] } , ts in epoch ms. One metric per call. which pairs a venue lists blackforge symbols({exchange}) usage / quota left blackforge usage() recent daily usage + rows remaining this month. CLI fallback maps 1:1: blackforge latest … , blackforge series … , blackforge symbols … , blackforge usage . Prefer output json when you will parse the result. Choosing interval for a series. The only valid values are 1m , 5m , 1h , 1d — anything else 400s. The interval is plan gated as well as size gated : asking finer than your plan's floor returns a 403 , not fewer points. 1m is ultra and payg only (payg bills a 1m row at 5x a 5m row); max floors at 5m ; pro at 1h ; free at 1d . Pick the coarsest interval that answers the question, and on a 403 step one rung coarser ( 1m → 5m → 1h → 1d ) rather than reporting no data. 1m rows only exist from the switch to one minute rows on ( availableFrom["1m"] in blackforge catalog ; null means not yet): a 1m series over an earlier range comes back empty, so use 5m there, which covers all history. Guard the 50k point cap — points ≈ span ÷ interval; when a range holds more, the response keeps the NEWEST buckets and says truncated: true : an hour or two, minute by minute → 1m on ultra/payg (50k points ≈ 34 days at 1m ) hours to a few days → 5m on max/ultra/payg · 1h on pro · 1d on free about a week to a month → 1h on max/ultra and pro · 1d on free multiple months → 1d (every plan) from / to are ISO 8601 UTC. If the user says "last week", compute the range from today and state the window you used. If a single call would exceed ~50k points, widen the interval or split the range. 3. Interpret the rows as measurements When you present numbers, define each column with its catalog description / howToRead wording (or the glossary). Convert quote relative values to USD when helpful by multiplying by quoteUsdRate (units are documented per metric). Anchor ts on the timeline. Compare windows in plain measurement terms — "taker buy volume was 2.3× taker sell volume", "median resting level lifetime dropped from 4.1s to 0.6s" — and stop there. Do not translate a measurement into a buy/sell call or label it with any banned word. Rollup notes. The rows are measured per minute; 5m , 1h and 1d are rollups of them (sums for flows, last value for book state, count weighted means for trade averages). For most columns the 5m rollup equals what a native 5 minute measurement would read. About three dozen do not, because they are measured within each minute (the 19 strong trade columns against a trailing five minute mean, liquidity removed, mirrored pairs, level flicker and lifetime, equal size groups, the trade gap mode, the 10 s / 60 s rise and drop). Those carry a one sentence rollupNote in blackforge catalog ; when you report one at 5m or coarser, say how it was rolled up, and do not compare its level across the switch to one minute rows as if nothing changed. Always read qualityFlags . It is the one column that qualifies every other column on the row, it is free on every plan, and it is deliberately queryable — request it alongside whatever else you ask for. It is a bitmask : 0 means no known problem, and each set bit names one condition. The full bit table ships on the catalog entry for qualityFlags as bits , and each bit carries a contaminates list of the metric families it calls into question — so a broken order book leaves the trade columns on the same row sound. Read the bit table from the catalog rather than hardcoding bit numbers. Nothing measured in a row is ever hidden, filtered or adjusted. Every value is exactly as measured; the flags tell you which of them to trust. The one thing never served is a placeholder: a column a row did not measure at all is null . Two companion columns are worth requesting with it: lastTradeAgeTime — how long before the window closed the pair last traded, 0 when the window itself contained a trade. About half of all windows contain no trade, and their candle carries the last traded price forward rather than inventing one. A large value means the price is real but old. bookObservedAt : the instant on our clock that the row's order book describes. From each venue's date in availableFrom.bookOnBoundary ( blackforge catalog ; null means not yet) the book is read as it stood at the window end, so bookObservedAt equals ts and two venues line up at the same ts . A row where it is later than ts (every earlier row) read the book late by the difference, by a different amount on each venue, so do not compare depth or best bid and ask across venues on such rows as if they were simultaneous. The book event columns (liquidity added and removed, level changes, flicker, lifetimes) follow the same switch: on boundary rows they cover the same window as the trades. The order book columns carry a one sentence bookTimingNote in blackforge catalog saying so. The QUALITY UNKNOWN flag (mask 32768) is not a defect. It means the row predates the quality rail and was never assessed — unchecked, not unreliable . It is the ClickHouse column default, so the entire pre migration 006 archive carries it. Say "not assessed", never "bad data". BOOK EMPTY AT VENUE (mask 131072) is not a defect either. The venue itself publishes no order book for the pair, so the empty book (it always comes with BOOK EMPTY ) is a fact about the venue. Say "the venue quotes no book for this pair", never "the book was lost". TRADES BACKFILLED (mask 262144) marks a window rebuilt later from the venue's public trade archive because the live window was lost. Its trade columns are real measurements; its book, enrichment and context columns come back null , and coarser buckets (1h, 1d) average only the windows that measured them. Report the trade figures and say the book was not observed then. Where a chart draws this, the convention is: wherever the mark is fainter or hollow, that bucket is flagged; solid means final. Five columns that 400 the WHOLE request if you name them in columns= . quoteAsset , baseAsset , enrichmentTs , bookSynced and missingTrades are identity/state fields, not data series. Naming any one of them fails the entire call — the columns you actually wanted included — with Unknown metric(s): … . They arrive on their own in a full response; just never ask for them by name. Use qualityFlags for the bookSynced / missingTrades conc