Futures · Order flow
Futures replenishment
/v1/futures/replenishmentfuturesReplenishmentThe order-flow bubbles of a window of at most 15 minutes that carry evidence from the observed-replenishment-v1 model: at least 3 classified prints and 100 contracts at one native price within a second, a best quote that stayed within one tick, and an observed increase of displayed size of at least 20 contracts at that price right after. Each row is the bubble (timestamp, price, side, size, prints) with its evidence (when the increase was observed, the volume and prints that preceded it, the size that was added). This is a heuristic on displayed size and executions: it does not prove hidden orders or icebergs, and an increase of displayed size can have other causes. side limits the rows to buy or sell aggressors. The window defaults to the last 5 minutes (413 range_too_large beyond 15 minutes, or for more than 2,000 rows) and reads the live capture, which holds the last 20 minutes: a window that starts earlier answers 422 data_unavailable. A held window without evidence answers an empty list. When the window holds more than 20,000 prints its rows are no longer single prints: the prints are grouped by second, native price and aggressor side (a coarser second when that is still too many groups), and a row with aggregated true is such a group, its prints the number of prints in it and its timestamp the last of them.
Example request
curl -sS --get "https://api.ordermap.si/v1/futures/replenishment" \
-H "Authorization: Bearer $ORDERMAP_API_KEY" \
--data-urlencode symbol=ESconst params = new URLSearchParams({
symbol: "ES",
});
const res = await fetch(`https://api.ordermap.si/v1/futures/replenishment?${params}`, {
headers: { Authorization: `Bearer ${process.env.ORDERMAP_API_KEY}` },
});
if (!res.ok) throw new Error(`${res.status} ${await res.text()}`);
const { data, meta } = await res.json();
console.log(data, meta.coverage);Set ORDERMAP_API_KEY to your key. Replace the dates with a recent trading date.
Parameters
5 parameters, none required.
| Parameter | Type and limits | Description |
|---|---|---|
symbolqueryoptional | stringat most 3 characterspattern ^[A-Za-z0-9]{1,3}$ | Futures product root, for example ES, NQ, CL or GC. Without contract the current front month is used and returned in the response. |
contractqueryoptional | stringat most 6 characterspattern ^[A-Za-z0-9]{1,3}[FGHJKMNQUVXZfghjkmnquvxz][0-9]{1,2}$ | Exact dated contract: root, month code and year, for example ESZ6 (December 2026). Two-digit years are accepted and returned in the one-digit form (ESZ26 is ESZ6). Only the front month and the contracts listed by /v1/futures/contracts are served. |
start_queryoptional | integerunix-msmin 946684800000max 4102444800000 | Start of the window (inclusive). |
end_queryoptional | integerunix-msmin 946684800000max 4102444800000 | End of the window (exclusive); at most 15 minutes after start_time. |
sidequeryoptional | stringbuysell | Only bubbles of this aggressor side. |
Response
| Status | Meaning | Body |
|---|---|---|
200 | Successful response. | Schema below |
400 | Invalid, unknown or repeated parameters, or an invalid cursor. | Error object |
401 | Missing or invalid API key. | Error object |
403 | The plan, dataset release or account state does not allow this request. | Error object |
422 | The request is valid but no data exists for it. | Error object |
429 | Rate limit, burst limit or cooldown; wait Retry-After seconds.Retry-After | Error object |
500 | Internal error. | Error object |
503 | Data temporarily unavailable; retry after Retry-After seconds.Retry-After | Error object |
504 | The request timed out. | Error object |
Authenticated responses carry the X-RateLimit-* headers (see rate limits); 429 and 503 add Retry-After.
200 response body
dataarray<object>required16 fields insideaggregatedbooleanrequiredTrue when the row is a group of prints (the window held more than 20,000 prints) rather than a single print.contractstringrequiredDated contract.evidenceobjectrequiredWhat the model observed.7 fields insidebasisarray<string>requiredThe conditions the model checked, in words.classified_volumeintegerrequiredClassified contracts at the price in that second.labelstringrequiredAlways possible absorption: a heuristic label.modelstringrequiredModel name and version.observed_atintegerunix-msrequiredWhen the increase of displayed size was observed. Unix epoch milliseconds (UTC).replenished_sizeintegerrequiredDisplayed size added at the price.trade_countintegerrequiredClassified prints at the price in that second.
pricenumberrequiredPrice of the bubble.price_ticksstringrequiredPrice in ticks, as a string.printsintegerrequiredPrints in the bubble.sidestringrequiredAggressor side of the bubble.buysellsizeintegerrequiredContracts in the bubble.timestampintegerunix-msrequiredTime of the last print of the bubble. Unix epoch milliseconds (UTC).
metaobjectrequiredMeta object
Example response
{
"data": [
{
"aggregated": false,
"contract": "ESZ6",
"evidence": {
"basis": [
"at least 3 classified prints and 100 contracts at the same native price within 1 second",
"heuristic association only; no hidden-order or iceberg inference"
],
"classified_volume": 120,
"label": "possible absorption",
"model": "observed-replenishment-v1",
"observed_at": 1792159200400,
"replenished_size": 30,
"trade_count": 3
},
"price": 6021.25,
"price_ticks": "24085",
"prints": 1,
"side": "sell",
"size": 40,
"timestamp": 1792159200300
}
],
"meta": {
"as_of": 1760659200123,
"coverage": {
"complete": true
},
"delay_ms": 0,
"delayed": false,
"request_id": "0199f0c2-5a1e-7c3b-9d4e-2b6f8a1c3d5e",
"source": "cme"
}
}Values are illustrative. Missing values are null, never 0.
