Skip to content
ChartDeck Developer API docs Account Get an API key

Strata pictures (any widget)

Any Strata widget as a PNG or WebP picture made for posting, drawn by the Strata page's own code with its parameters - sizes, prices, limits, errors.

GET /v1/pictures/strata/<widget>.png (or .webp) answers a picture of one Strata widget, drawn by the Strata page's own code from the same data a member sees. It needs the charts:read scope. Every widget takes the controls the page offers it, with the page's defaults.

Text
GET https://api.chartdeck.trade/v1/pictures/strata/heatmap.png?coin=ETH&half_life=24&threshold=10&side=long&theme=light
Authorization: Bearer cdk_...

#Two layouts

  • layout=frame (the default since 1.3.10) is a picture made for posting: no buttons, no controls, no footnotes. The frame is 1600 x 900 CSS pixels by default, drawn at scale=2, so the file is 3200 x 1800 pixels. It is always the same composition: width only makes it larger or smaller, so the type stays readable when a chat shows the picture small. These widgets have a frame today: levels, heatmap, netpos, replay (one step of the replay: the newest, or the one step names), hl, realized, screener, calibration, blocks, oi, terrain, whales, funding, fundclock, context, divergence and the cross-coin widgets. The table-like ones (realized, screener, calibration, blocks, oi, context, expertgrid) are as tall as their content instead of 16:9 (tables show at most 15 rows; the screener's picture carries open interest and price with their 7-day and 24-hour moves, funding, the long/short ratio and one trend sparkline, not every column of the card) and refuse height. A frame comes in two looks (style); levels, heatmap and netpos have both, the other widgets answer the flat look for either value:
    • style=flat (the default): a flat black frame with the chart edge to edge. A thin strip names the widget; two centered text lines give the coin, venue and window, how the numbers are made ("modeled from open interest"), and the widget's key numbers; nothing lies over the chart; the time the picture was drawn (UTC) is at the bottom left. The heatmap and Net Positions are drawn as the grid itself in crisp rows (no smoothing), filled from the lowest color of the scale, with a color scale bar at the left and a thin one-color price line. Liquidation Levels are colored by leverage tier where the venues export it, with realized liquidations as circles and the long-minus-short delta as a panel under the chart.
    • style=glass: a title line (the widget, the coin, venue and window, a MODELED tag, ChartDeck and the draw time), then the chart with the key numbers in glass blocks inside it, placed where they cover no part of the price and the least of the data, and the color legend.
  • layout=page is the card exactly as the Strata page draws it, with the page's buttons, stat tiles and notes (the picture before 1.3.10). Its height is the card's own.

A widget that has nothing to draw for your request (a coin Strata does not carry, no data for that venue or window) answers 404 no_data as JSON, with the widget's own words in the message. A picture is never a photograph of an empty or failed card.

#Parameters every picture takes

parametervaluesdefault
layoutframe (the share picture) or page (the page's card)frame where the widget has one
stylelayout=frame only (a page card reads it and changes nothing): flat or glass, the two looks aboveflat
themedark, light (the page's themes). The flat frame is designed dark first: on light the frame and text turn white and dark, the heat field keeps its own colorsdark
langthe page's 17 languages: en, es, pt-BR, fr, de, it, tr, ru, uk, zh-CN, zh-TW, ja, ko, hi, ar, id, vien
widthCSS pixels, 360 to 2400. layout=frame: the frame's width. layout=page: the card's width (a half-width card: 430 to 1200); the card is laid out as on the page in a window that wide (+32 px; a half card: twice as wide + 48 px), so below about 870 px a wide card takes the page's narrow-screen layout1600 (frame), 1200 (page)
heightlayout=frame only: the frame's height in CSS pixels, 240 to 2400; the width must be 1 to 3 times the height. Refused (400 not_applicable) on layout=page (the height is the card's own) and by the table-like widgets (as tall as their content)16:9 of the width (900 at 1600)
scale1, or 2 for twice the pixels (sharper text) at the same price2 (frame), 1 (page)
attributionheader = a clean picture, the sources only in X-Attribution (show them yourself); strip = the sources also printed in the picture (one line under the chart of a frame, under the card of a page picture)header
spanlayout=page only: wide (a full row on the page) or half (half a row: smaller charts). A frame picture reads it and changes nothingthe widget's own

A call from before 1.3.10 keeps working: width=1200 now answers the frame at 1200 x 675 CSS pixels (2400 x 1350 pixels at the default scale); add layout=page for the old card.

The file name decides the format: .png is lossless (a default style=flat frame is about 0.3 to 0.4 MB at 3200 x 1800: flat fields compress well; a style=glass frame is 0.8 to 2.2 MB, and about 8 times smaller as WebP); .webp is lossy at quality 90 (0.2 to 0.3 MB at 3200 x 1800 in either look) and not pixel-exact.

The page's control bar: coin (BTC, ETH, 1000PEPE; symbol=BTCUSDT is read the same), venue (all = every venue the model uses, or one venue id), window (7d; 30d from the Developer tier), half_life (6 to 168 hours in steps of 6, default 48), threshold (0 to 60 % of the peak in steps of 2, default 0) and side (both, long, short). A widget reads only the ones in its row below.

#The widgets and their own controls

widgetwidth on the page (layout=page)readsits own controls (default)
levelswidecoin venue window half_life threshold sidecolor distance / cohort (distance; cohort = by leverage tier in a style=flat frame)
heatmapwidecoin venue window half_life threshold side-
replaywidecoin venue window half_life threshold sidestep -1 to 10000 (-1 = now, 0 = the oldest column)
hlwidecoinrange full / 25 / 10 (full); model true / false (true); estimate true / false (false)
realizedwidecoin venue window sidescope sym / all (all); mode bars / bubbles (bars); period 0 / 12 / 24 (0 = the whole window)
netposwidecoin venue windowmetric long / short / delta = net longs, net shorts or their difference from order flow (default delta); oi = the open-interest map
whaleswide-field net / long / short / chg (net)
fundingwidecoin windowunit apr / 8h / raw (apr); view rate / cum (rate)
screenerwide-sort oi / oi24h / px24h / fund / lsr / liq (the page's: open interest)
contexthalfcoin-
calibrationwidecoin venue window-
blockshalf--
oihalf--
serieswidecoin window-
expertgridwide--
terrainwidecoin venue window half_life threshold sideramp heat / viridis (heat)
fundclockhalfcoin-
rankmapwidecoinindicator an indicator (oi); mode value / change (value); order desc / asc (desc); hours 24 / 72 / 168 (168)
quadranthalfcoinx an indicator (oi_change); y an indicator (price_change); split auto / zero / median (auto); mode value / change (value); hours 24 / 72 / 168 (168)
correlationhalfcoinindicator an indicator (oi); order cluster / book / name (cluster); hours 24 / 72 / 168 (168)
paircorrwidecoinindicator an indicator (price); pair a second coin (the page's: the biggest other book); bars 12 / 24 / 36 (24); hours 24 / 72 / 168 (168)
spaghettiwidecoinindicator an indicator (oi); show all / movers / book (all); hours 24 / 72 / 168 (168)
distributionwidecoinindicator an indicator (oi); mode value / change (value); hours 24 / 72 / 168 (168)
profileswidecoinindicator an indicator (liq_notional); value_area 60 / 70 / 80 (70); rows 24 / 40 / 60 (40); hours 24 / 72 / 168 (168)
coinmatrixwidecoinx an indicator (oi_change); y an indicator (price_change); z an indicator (oi); third_as size / color / both (both); split auto / zero / median (auto); mode value / change (value); hours 24 / 72 / 168 (168)
stackerwidecoinindicator an additive indicator: open interest, liquidations, volume, trades or the Hyperliquid levels (oi); show all / cur (all); bands 6 / 10 / 16 (10); hours 24 / 72 / 168 (168)
timegridwidecoinmode value / change (value); hours 24 / 72 / 168 (168)
coinpulsewidecoinhours 24 / 72 / 168 (168)
divergencewidecoinmetric funding / price / oishare (funding); hours 6 / 24 / 72 (24)

"An indicator" is one of the 34 indicators of the Relationships widgets by key (oi, price, funding_rate, liq_notional ...), optionally anchored: @4h, @1d, @1w, @1M (and @1h for flows), e.g. indicator=oi@1d. The full list of values of every parameter is on the operation's reference page.

A parameter a widget does not read is refused (400 not_applicable, the message lists the widget's parameters); a name no widget reads is 400 unknown_param; a value off the list is 400 invalid_param with the allowed values or range (for example "half_life must be a whole number from 6 to 168 in steps of 6").

#Price and limits

  • 20 units per picture, whatever the widget, the size and the scale (since 1.3.10 scale=2 costs the same as scale=1); +5 for window=30d. A cached picture costs the same (the price is per call, as for every route). A 404 no_data answer costs one unit.
  • Pictures per key per minute: Starter 20, Developer 60, Business 120 (Elite's included tier: 20). Over it: 429 picture_rate_limited with Retry-After, and the call costs nothing. This is the per-minute limit of a picture: since 1.3.10 pictures count toward your tier's units per month only, not against its units per minute (Units and weights).
  • width and height at most 2400 and scale at most 2.
  • The sandbox has no Strata pictures (404 not_in_sandbox); chart pictures work there.

#Caching, attribution, errors

  • One render per parameter set and data version, kept 45 seconds and shared by every caller: Cache-Control: private, max-age=<seconds left> says how long the picture stays the same. New Strata data is a new picture at once.
  • Attribution (the API terms): the picture carries no sources line by default, and X-Attribution carries its sources (joined by |): the exchanges and the model whose data the picture shows. Show them wherever you post the picture. With attribution=strip the picture prints "Sources: ..." for you (a frame picture: one line under the chart; a page picture: under the card, with the time it was drawn). A frame picture always shows the time it was drawn (UTC) in its title line.
  • The picture is never a half-drawn card: while the renderer is busy or restarting, or when the data the widget shows did not load, the answer is a JSON error with Retry-After (503 render_busy, render_timeout, renderer_unavailable, upstream_unavailable; 502 picture_failed). Retry after the given seconds. See Errors.
  • Nor is it a picture of nothing: 404 no_data means the widget has no data for this coin, venue or window (the message carries the widget's own words, for example "No liquidation data for this market."). Do not retry it unchanged.
  • A change to a widget on the Strata page changes its picture the same day: pictures follow the page's data and drawing code. Changes are listed in the Changelog.

#A bot posting a widget

JavaScript
const res = await fetch('https://api.chartdeck.trade/v1/pictures/strata/levels.webp?coin=SOL&theme=dark', {
  headers: { Authorization: `Bearer ${process.env.CHARTDECK_API_KEY}` },
});
if (!res.ok) {
  const { error } = await res.json();                       // errors are JSON: { error: { code, message } }
  throw new Error(`${error.code}: ${error.message} (retry after ${res.headers.get('retry-after') ?? '-'} s)`);
}
const picture = Buffer.from(await res.arrayBuffer());       // image/webp, 3200 x 1800; the sources are in X-Attribution

With the SDKs: await cd.pictures.strata('heatmap', { coin: 'BTC', half_life: 24 }) and cd.pictures.strataWebp(...) (JavaScript), client.pictures.strata('heatmap', coin='BTC', half_life=24) and client.pictures.strata_webp(...) (Python) return the image bytes as data and the attribution lines in meta.attribution. They retry 503 answers after Retry-After by themselves.

The Developer API documentation is in English.