Futures · Statistics
Futures roll
/v1/futures/rollfuturesRollThe front month and the next listed contract of a product with the spread between their latest closes (next minus front, in points and ticks), their volume on each of the last 10 sessions and the next contract's share of the two, and roll_progress, the share on the latest session that has volume in both. roll_state is front under 0.15, rolling up to 0.5 and rolled above. days_to_last_trade is the calendar days from today to the final settlement date and is given for equity-index products only. Reads the listed contracts and the daily bars of each of the two contracts through a deferred history read, so a first request can answer 503 data_pending; retry. Fields that need the next contract are null when none is listed. The statistics use the last 10 sessions whatever your plan's history window; only dated daily rows older than that window are left out of the response, and coverage says when they were.
Example request
curl -sS --get "https://api.ordermap.si/v1/futures/roll" \
-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/roll?${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
1 parameter, 1 required.
| Parameter | Type and limits | Description |
|---|---|---|
symbolqueryrequired | stringat most 3 characterspattern ^[A-Za-z0-9]{1,3}$ | Futures product root, for example ES. |
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
dataobjectrequiredThe roll of one product.13 fields insidedailyarray<object>requiredThe last sessions, oldest first.4 fields insidedatestringdaterequiredTrading date.front_volumeinteger | nullrequiredContracts of the front month.next_sharenumber | nullrequirednext_volume over the two contracts' volume.next_volumeinteger | nullrequiredContracts of the next contract.
days_to_last_tradeinteger | nullrequiredCalendar days to the final settlement date (equity-index products).front_contractstringrequiredFront month.next_contractstring | nullrequiredThe next listed contract.roll_progressnumber | nullrequiredThe next contract's share on the latest session with volume in both.roll_statestring | nullrequiredfront under 0.15, rolling up to 0.5, rolled above.frontrollingrollednullspreadnumber | nullrequiredLatest next close minus latest front close, in points.spread_ticksnumber | nullrequiredspread in ticks.symbolstringrequiredProduct root.
metaobjectrequiredMeta object
Example response
{
"data": {
"daily": [
{
"date": "2026-10-16",
"front_volume": 1281930,
"next_share": 0.011,
"next_volume": 14210
}
],
"days_to_last_trade": 63,
"front_contract": "ESZ6",
"next_contract": "ESH7",
"roll_progress": 0.011,
"roll_state": "front",
"spread": 31.25,
"spread_ticks": 125,
"symbol": "ES"
},
"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.
