Local data API on Bookmap
This page covers the Pulling & Stacking Indicator on Bookmap, where it runs as an add-on, with its flow panel under the heatmap.
On Bookmap, the indicator can serve its line values to another program on the same computer: a spreadsheet, a script, your own dashboard. It is a single read-only web address that returns JSON; your program asks for it as often as it likes (every few seconds is plenty).
The local data API is available on Bookmap only. Using market data in other programs may need a licence from your data provider; on Bookmap, instruments whose data licence allows display only are left out.
Switching it on
It is off by default. In Configure add-ons → Pulling & Stacking Indicator → Console & Chart Markers, tick Enable the local data API, and optionally set a port and an API key. It applies at once and the panel shows the status.
The status reads Listening on http://127.0.0.1:8787/v1/flow.
Only this computer
It listens on 127.0.0.1, so another computer cannot reach it, even on your
own network. With an API key set, every request must carry it in the
X-API-Key header (or ?key= in the address); without it the reply is
401. The key keeps other programs on this computer out. It is sent in plain
text, which is why the API never leaves the computer.
A web page in a browser cannot read it.
Asking for the data
curl -H "X-API-Key: my-key" http://127.0.0.1:8787/v1/flow
import requests, time
while True:
data = requests.get("http://127.0.0.1:8787/v1/flow",
headers={"X-API-Key": "my-key"}, timeout=3).json()
for inst in data["instruments"]:
if not inst.get("available", True): # left out, see below
continue
five = next(w for w in inst.get("windows", []) if w["minutes"] == 5)
print(inst["symbol"], inst["line"], five["total"], five["sigma"])
time.sleep(5)
What comes back
One document for every instrument the indicator is loaded on.
{
"apiVersion": 1, "indicatorVersion": "3.0.23", "platform": "bookmap",
"time": "2026-10-14T09:31:05",
"instruments": [
{ "symbol": "BTC-USDT", "hasData": true, "stale": false,
"lastEvent": "2026-10-14T09:31:05",
"line": "Total Flow", "mode": "flow", "primaryMinutes": 5,
"headline": "Total Flow +1.2σ (5m)",
"state": "INITIATIVE - book and tape aligned",
"windows": [
{ "minutes": 5,
"total": 5494, "passive": -3353, "aggressive": 8847, "placement": -12200,
"sigma": 1.2, "warm": true, "provisional": false,
"sigmaTotal": 1.2, "sigmaPassive": -0.8, "sigmaPlacement": -2.1,
"bandTotal": 12299.18, "bandPassive": 9100.5, "bandPlacement": 15020.25,
"flowBandWarm": true }
] }
]
}
(The numbers above are an example; windows always holds the 2, 3, 5 and 10
minute windows.)
| Field | Meaning |
|---|---|
line, mode |
The line the chart is set to, and flow or buysell. With Console Mode Same as chart this is also what the console tile shows. |
sigma, warm, provisional |
The reading of that line, as on the console badge with Console Mode Same as chart. null while the band is warming. |
total, passive, aggressive, placement |
The four Flow lines over that window, in contracts. |
sigmaTotal, sigmaPassive, sigmaPlacement |
Each line in units of its own band's σ. |
bandTotal, bandPassive, bandPlacement |
Each line's band: Resistance is plus, Support minus this value. |
buy, sell, buySigma, sellSigma, resistance, support |
Buy / Sell mode only: both lines, their σ from the band's centre, and the band. |
stale |
No flow for longer than the stale timeout. |
hasData |
False until the instrument has delivered market data. |
available |
true when the API serves the instrument's data. false for an instrument the API leaves out: see below. |
reason |
Only when available is false: why the instrument is left out, in plain English. |
A number that cannot be computed is null. Other replies: 401 wrong or
missing key, 404 unknown address, 405 anything other than GET.
Instruments the API leaves out (Bookmap)
Some market data may only be shown on screen. The licence for that data allows display in Bookmap only, and does not allow passing it on to other programs. Real-time CME data from Bookmap is an example. Bookmap tells the indicator which instruments have such a licence.
On those instruments the indicator works as usual: the chart, the console,
the alerts, the arrows and the MARKER lines are all there. Only the local
data API leaves them out. It still lists the instrument, so your program can
see why its data is missing, but with no values at all: no windows, lines,
σ, bands, headline, state or timestamps.
{ "symbol": "INSTRUMENT", "available": false,
"reason": "The licence for this instrument's data allows display in Bookmap only, so the local data API does not provide it." }
Every other instrument has "available": true and all the fields above. If
every loaded instrument is left out, the API still answers, with only entries
like the one above.
The settings panel says the same under Enable the local data API, and the
status line names the instruments left out, for example
Not available for INSTRUMENT (display-only data licence). When the API is on, the
console's log also notes each one once, for example
Local data API: INSTRUMENT is not included (display-only data licence).
Older Bookmap versions do not tell the indicator what an instrument's data
licence allows. There the API serves crypto instruments only and leaves out
every other instrument, with the reason "This version of Bookmap does not
report the licence for this instrument's data, so the local data API does
not provide it." The status line then reads, for example,
Not available for INSTRUMENT (data licence not reported by this Bookmap version).
Limits
- The current reading only; there is no history.
- A program on another computer cannot reach it.
- It reports what the console holds, refreshed about twice a second. Asking more often than that returns the same values.
- It always reports the chart's lines. If Console Mode
makes the console tile read the other family,
line,mode,headlineandsigmastill describe the chart, so a program reading them sees no change; the Flow figures (total,sigmaTotaland so on) are there in either mode. apiVersionis 1. Fields may be added; existing ones will not change meaning without a new version.