Integrations / Bookmap
FirmTape levels in Bookmap
Two routes onto the heatmap: an add-on that draws the levels as lines, redrawn every second, or Cloud Notes with nothing to install. These are measurements of dealer positioning, not trade signals: the plugin places no orders and raises no alerts.
What you need
- Bookmap, live or replay. The add-on route needs API add-ons enabled on the Bookmap licence (below); Cloud Notes does not.
- A FirmTape account on the LIVE plan, and an integration token.
Get a token
- Hold the LIVE plan. The levels API and every integration are part of it.
- Open /account#integrations, section Integrations, and press Create integration token. Give it a name (for example the platform and the machine).
- Copy the token when it is shown: it starts
ftpl_and is shown once. It reads levels only; it cannot run LAB or spend credits.
Install
- Enable API add-ons on the Bookmap licence. Bookmap loads third-party .jar add-ons only when the licence has API access. If it is not on, write to
[email protected]with the licence key or registration email and ask for API add-ons to be enabled. - Download the add-on's .jar below.
- In Bookmap: Settings > API plugins configuration (or the Configure API plugins button), Add..., pick the .jar, choose FirmTape Levels.
- Enable it for the chart, then press its settings button and paste your token into API token. Press Apply and reload.
- The Status box shows the last answer, for example
ES open (ESZ26): flip 6752.25, call res 6800, put sup 6700, net gamma negative, book 1 s old, or the error. The same lines go to the Bookmap log.
Cloud Notes: the route with nothing to install
Bookmap can load price notes from a CSV at a URL and reload it on a timer. FirmTape serves its levels in that format, so one URL puts the flip and the walls on the heatmap as notes with a horizontal line, without the add-on and without API access on the licence.
- Build the URL with your symbols and your token:
https://firmtape.com/api/v1/bookmap.csv?sym=ES,NQ&key=ftpl_YOUR_TOKEN
- In Bookmap, set a column to Notes > Cloud Notes and add the URL under Notes URLs.
- Set the Refresh Interval (Bookmap allows 5 seconds to 10 minutes).
Parameters: sym (up to 20, as in the levels API; MES and MNQ accepted), oi=1 adds the
open-interest book's three levels, automap=none drops the #automap RITHMIC line and writes
full aliases, and alias= (a comma list aligned with sym) writes the exact Bookmap alias
for a feed the default mapping gets wrong. ES and NQ are written as the dated contract of the reading
(ESZ6); tickers as QQQ@DXFEED. For SPX, pass the alias your index feed uses. Without an active
LIVE plan the sheet answers empty, so old notes go. Cloud Notes cannot send headers, so the token rides in
the URL: use a token made for this alone.
Settings
| Setting | Default | What it does |
|---|---|---|
| API token | blank | Your ftpl_ token. Stored in Bookmap's local settings for that instrument; never logged. |
| FirmTape symbol | blank | Blank takes it from the chart (ESZ6 and MESZ6 read ES; NQH7 and MNQ read NQ; QQQ@DXFEED reads QQQ). Type one to override, for example SPX on an index feed. |
| Poll every (s) | 5 | 3 to 60. |
| Also draw the open-interest book | off | Three extra dashed lines. |
What is drawn
- The volume book's zero-gamma flip, call resistance and put support as lines on the heatmap, redrawn every second from the newest reading. Colours and widths can be changed in Bookmap's own settings for each line.
- Optionally the open-interest book's three levels, thinner and dashed.
- Lines start when the add-on loads; earlier hours of the chart are not backfilled.
- ES and NQ answer for the contract the basis was measured on, and the status names it. If the chart is on another month (roll week), the status adds a NOTE, because the offset then differs by the calendar spread.
- Every level is FirmTape's volume book, the one the terminal draws; the open-interest book is the optional set.
- ES and NQ are the SPX and NDX books moved by the day's basis (the running median of the day's basis measurements from put-call parity, rounded to 0.25), exactly as the terminal draws them. MES and MNQ read the same levels as ES and NQ.
- Cadence: SPX and ES are rebuilt every second; NQ and the tickers carry a book rebuilt every five minutes and a price of the second.
- Gamma units are named by the API: millions of USD per index point for SPX and ES, USD per 1% move for NQ and the tickers. Compare bar lengths within one chart, not across charts.
Requests and limits
The levels API allows 120 requests a minute per token, counted across everything that uses it; an unchanged
reading answers 304 with no body and does not count. The add-on polls one symbol every 5 s by default (12 requests a minute) and shares one poller per token and symbol across every chart of that symbol, so a token covers several charts and a script.
Troubleshooting
| Status says | Meaning and fix |
|---|---|
401 bad_key | The token is wrong or revoked. Create a new one on /account#integrations. |
403 live_required | The account holds no active LIVE plan. |
429 rate_limited | Over 120 requests a minute on this token. Poll less often or use a second token. |
ES: no_basis | The day's futures basis is not measured yet. The lines keep their last values until it is. |
stale | Market hours, but the book has not moved for a while. |
The add-on cannot be added | The licence has no API add-on access yet (step 1), or use Cloud Notes instead. |
More
- Tokens and the TradingView and thinkorswim levels string: /account#integrations.
- The levels API reference: /api/v1 (OpenAPI).
- Every platform: /integrations.
Beta software, provided as is, not yet verified inside every version of Bookmap. Bookmap is a trademark of its owner; no affiliation with, or endorsement by, it is implied. Not investment advice.