# Futures Roll Calendar & Front-Month API (CME) (`vikingtrading/futures-roll-calendar`) Actor

Current front-month contract, roll date, last trading day, first notice day, tick value and broker symbol formats for ES, NQ, CL, GC, ZN, 6E and 20+ CME futures. Deterministic, no scraping, built for trading bots and AI agents.

- **URL**: https://apify.com/vikingtrading/futures-roll-calendar.md
- **Developed by:** [Patrick](https://apify.com/vikingtrading) (community)
- **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $7.00 / 1,000 contract results

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.
Since this Actor supports Apify Store discounts, the price gets lower the higher subscription plan you have.

Learn more: https://docs.apify.com/actors/running/actors-in-store.md#pay-per-event

## What's an Apify Actor?

An Actor is a serverless cloud program that runs on the Apify platform. It has two run modes.
In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours,
and optionally produces a well-defined JSON output, datasets with results, or files in key-value store.
In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server.

Apify vocabulary and the platform model are defined once, in the agent quickstart at https://apify.com/agents.md.

## How to integrate an Actor?

If asked about integration, you help developers integrate Actors into their projects.
You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready.

Do not guess an integration path. Every one of them is in the agent quickstart at https://apify.com/agents.md: the Apify MCP server, Agent Skills with the Apify CLI, the JavaScript and Python clients, the REST API, and the account-free path for an agent with no human to sign in. It also carries the rule on stating cost before the first paid run.

For examples already wired to this Actor's own input schema, see the [API](#api) section below.

Each client library has reference documentation the quickstart does not restate: [JavaScript/TypeScript](https://docs.apify.com/api/client/js/docs.md) (`npm install apify-client`) and [Python](https://docs.apify.com/api/client/python/docs.md) (`pip install apify-client`).

# README

## Futures Roll Calendar & Front-Month API (CME)

**Which futures contract should my bot trade today, and when do I roll?** This Actor answers that for ES, NQ, CL, GC, ZN, 6E and 20+ other CME Group futures. It returns the active contract, next contract, roll date, last trading day, first notice day, tick value, and symbol formats ready for CME, TradingView, NinjaTrader and Interactive Brokers.

Everything is **computed from the exchanges' published expiration rules and US exchange holidays**. There is no scraping, no third-party data feed and no API key, so runs are fast, cheap and reproducible. Past dates work too, which makes it useful for backtests.

### What you get per symbol

| Field | Example (ES, as of 2026-10-20) |
|---|---|
| `activeContract.code` | `ESZ6`, the contract to trade now |
| `activeContract.rollDate` | `2026-12-14`, the CME equity roll date |
| `activeContract.lastTradingDay` | `2026-12-18` |
| `activeContract.firstNoticeDay` | `null` (cash-settled); set for GC, ZN and other physically delivered contracts |
| `activeContract.daysToRoll` | `55` |
| `activeContract.symbols` | `ESZ6`, `ESZ26`, `ESZ2026`, `ES 12-26` (NinjaTrader), `202612` (IB), `CME_MINI:ESZ2026` (TradingView) |
| `nextContract` | `ESH7` with the same fields |
| `expiringContract` | The nearest contract that has not expired yet; differs from the active one during the roll window |
| `spec` | Contract unit, tick size, tick value in USD, settlement type, listed cycle |
| `session` | CME Globex hours and daily break |
| `isBusinessDay`, `holiday` | Whether the as-of date is an exchange business day |

### Supported contracts

| Group | Symbols | Expiration rule |
|---|---|---|
| Equity index | ES, MES, NQ, MNQ, RTY, M2K, YM, MYM | 3rd Friday of Mar/Jun/Sep/Dec (prior business day if that Friday is a holiday) |
| FX | 6E, M6E, 6B, 6J, 6A, 6S | 2 business days before the 3rd Wednesday of the contract month |
| Energy | CL, NG, RB, HO | NYMEX monthly rules (e.g. CL: 3 business days before the 25th of the prior month) |
| Metals | GC, MGC, SI, HG | 3rd last business day of the contract month; first notice day = last business day of the prior month |
| US Treasuries | ZN, TN, ZB, UB, ZF | 7 business days before the month's last business day (ZF: last business day); first notice day as above |

Aliases such as `TY`, `US`, `FV`, `EC`, `BP` and `JY` are accepted.

### How the roll date is chosen

- **Equity index:** the CME roll convention, the Monday before the 3rd Friday of the contract month.
- **FX:** 5 business days before the last trading day.
- **Energy:** 3 business days before the last trading day, when volume usually moves to the next month.
- **Metals and Treasuries:** 3 business days before the first notice day, so long positions are out before the delivery period.

Every row states the method used in `rollMethod`. To apply your own rule, set `rollBusinessDaysBeforeExpiry`.

### Modes

**`active` (default):** one row per symbol.

```json
{ "symbols": ["ES", "MNQ", "CL", "GC", "ZN", "6E"] }
```

**`schedule`:** the next N contracts per symbol with all dates, useful for building a roll calendar.

```json
{ "mode": "schedule", "symbols": ["CL"], "contractsAhead": 12 }
```

**`holidays`:** US exchange holidays used for business-day counting.

```json
{ "mode": "holidays", "year": 2027 }
```

**Backtests:** set `asOf` to any past date, for example `"asOf": "2020-03-16"`.

### Use it from code, automations and AI agents

Synchronous call that returns the rows directly:

```bash
curl -X POST "https://api.apify.com/v2/acts/UbgWBltR3JhrHLbAR/run-sync-get-dataset-items?token=<APIFY_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{"symbols": ["ES", "NQ"]}'
```

```python
from apify_client import ApifyClient

client = ApifyClient("<APIFY_TOKEN>")
run = client.actor("UbgWBltR3JhrHLbAR").call(run_input={"symbols": ["ES", "CL"]})
for row in client.dataset(run["defaultDatasetId"]).iterate_items():
    print(row["symbol"], row["activeContract"]["code"], row["activeContract"]["rollDate"])
```

The ID `UbgWBltR3JhrHLbAR` is this Actor's permanent ID. The **API** tab on this page shows the same calls with the Actor's name.

**AI agents (Claude, ChatGPT, Cursor and other MCP clients):** connect the Apify MCP server at `https://mcp.apify.com` and add this Actor as a tool. The **API → MCP** tab on this page has the ready-made configuration. The agent can then answer questions like "What is the current NQ front month and when does it roll?"

**No-code:** works with Make, n8n and Zapier through the Apify integration. Typical setup: run daily with Apify Schedules and send an alert to Slack or Telegram when `daysToRoll` reaches 2.

### Typical use cases

- Trading bots that must switch to the next contract automatically
- Roll alerts for discretionary futures traders
- Building continuous-contract series and backtests with correct expiration dates
- Prop-firm and journal tools that need the right symbol per date
- AI trading assistants that need reliable contract facts instead of guesses

### Pricing

Pay per result: **$0.01 per row** (one row per symbol in `active` mode, one per contract in `schedule` mode, one per holiday in `holidays` mode), with lower prices on higher Apify plans, plus Apify's small standard start fee per run. Unsupported symbols cost nothing. A daily check of 5 symbols costs about $1.50 per month.

### Limitations

- Dates follow the published rules and the regular US exchange holiday calendar. Unscheduled closures, for example a national day of mourning, cannot be known in advance; add them via `extraHolidays`.
- FX contracts can shift when a foreign bank holiday falls on a settlement-relevant date; the rule here uses US exchange business days.
- Holiday trading hours and early closes are not modelled. The `session` field shows the regular Globex schedule.
- This is reference data, not a live market feed. It contains no prices, margins or fees.

### Disclaimer

Not affiliated with or endorsed by CME Group. Contract rules can change. Verify critical dates with the exchange or your broker before relying on them for live orders. Not investment advice.

# Actor input Schema

## `mode` (type: `string`):

active: one row per symbol with the contract to trade now, the next contract and the expiring one. schedule: the next N contracts per symbol with all dates. holidays: the exchange holiday list for a year.

## `symbols` (type: `array`):

Root symbols such as ES, MES, NQ, MNQ, RTY, YM, CL, NG, RB, HO, GC, MGC, SI, HG, ZN, ZB, ZF, TN, UB, 6E, M6E, 6B, 6J, 6A, 6S. Up to 50 per run. Unsupported symbols are returned as free error rows.

## `asOf` (type: `string`):

Date to evaluate (YYYY-MM-DD). Leave empty for today in Chicago time. Use past dates for backtests.

## `contractsAhead` (type: `integer`):

How many upcoming contracts to list per symbol in schedule mode.

## `year` (type: `integer`):

Year for the holiday list. Defaults to the year of the as-of date.

## `rollBusinessDaysBeforeExpiry` (type: `integer`):

Optional. Overrides the default roll rule for all symbols: roll this many business days before the last trading day (equity index, FX, energy) or before the first notice day (metals, Treasuries).

## `extraHolidays` (type: `array`):

Optional unscheduled exchange closures (YYYY-MM-DD), e.g. a national day of mourning. They are excluded from business-day counting.

## Actor input object example

```json
{
  "mode": "active",
  "symbols": [
    "ES",
    "NQ",
    "CL",
    "GC"
  ],
  "contractsAhead": 4
}
```

# Actor output Schema

## `overview` (type: `string`):

Active contract, roll date, last trading day and next contract per symbol.

## `results` (type: `string`):

Complete rows including symbol formats, contract specs, session hours and schedule fields.

# API

You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup.

## JavaScript example

```javascript
import { ApifyClient } from 'apify-client';

// Initialize the ApifyClient with your Apify API token
// Replace the '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {
    "symbols": [
        "ES",
        "NQ",
        "CL",
        "GC"
    ]
};

// Run the Actor and wait for it to finish
const run = await client.actor("vikingtrading/futures-roll-calendar").call(input);

// Fetch and print Actor results from the run's dataset (if any)
console.log('Results from dataset');
console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`);
const { items } = await client.dataset(run.defaultDatasetId).listItems();
items.forEach((item) => {
    console.dir(item);
});

// 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs

```

## Python example

```python
from apify_client import ApifyClient

# Initialize the ApifyClient with your Apify API token
# Replace '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = { "symbols": [
        "ES",
        "NQ",
        "CL",
        "GC",
    ] }

# Run the Actor and wait for it to finish
run = client.actor("vikingtrading/futures-roll-calendar").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print(f"💾 Check your data here: https://console.apify.com/storage/datasets/{run.default_dataset_id}")
for item in client.dataset(run.default_dataset_id).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{
  "symbols": [
    "ES",
    "NQ",
    "CL",
    "GC"
  ]
}' |
apify call vikingtrading/futures-roll-calendar --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,vikingtrading/futures-roll-calendar"
        }
    }
}
```

The hosted server signs you in with OAuth on first connect, so no API token belongs in this config. Clients without OAuth support can send an `Authorization: Bearer <APIFY_API_TOKEN>` header instead, using a token from API & Integrations in Apify Console (https://console.apify.com/settings/integrations).

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/UbgWBltR3JhrHLbAR/builds/vR2FVvnHKTL29TzeN/openapi.json