Skip to content

Futures · Order flow

Futures replenishment

Order-flow bubbles where displayed size grew back after executions, a heuristic (not hidden orders).
GET/v1/futures/replenishmentfuturesReplenishment
On this page

The 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=ES

Set ORDERMAP_API_KEY to your key. Replace the dates with a recent trading date.

Parameters

5 parameters, none required.

ParameterType and limitsDescription
symbolqueryoptionalstringat 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.
contractqueryoptionalstringat 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_timequeryoptionalintegerunix-msmin 946684800000max 4102444800000Start of the window (inclusive).
end_timequeryoptionalintegerunix-msmin 946684800000max 4102444800000End of the window (exclusive); at most 15 minutes after start_time.
sidequeryoptionalstringbuysellOnly bubbles of this aggressor side.

Response

StatusMeaningBody
200Successful response.Schema below
400Invalid, unknown or repeated parameters, or an invalid cursor.Error object
401Missing or invalid API key.Error object
403The plan, dataset release or account state does not allow this request.Error object
422The request is valid but no data exists for it.Error object
429Rate limit, burst limit or cooldown; wait Retry-After seconds.Retry-AfterError object
500Internal error.Error object
503Data temporarily unavailable; retry after Retry-After seconds.Retry-AfterError object
504The 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 inside
    • aggregatedbooleanrequiredTrue 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 inside
      • basisarray<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.buysell
    • sizeintegerrequiredContracts 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.