Futures API reference

Overview

Prices and price history for 29 futures: commodities, stock indexes, Treasuries and currencies. Every request needs a Bearer key, and REST and MCP share one account quota.

An id is the exchange's root code, such as CL for WTI crude oil, GC for gold, ES for the E-mini S&P 500 or 6E for the euro. Any case works. The list route returns every id with its name, category, exchange, currency and unit.

Each series is the front month contract, joined end to end and not adjusted. On the day the front month changes, the price steps from one contract to the next. That step is in the data as it traded.

Base URL: https://api.narwhalapi.com. The MCP tool is futures, with one action for each route below.

Plans and limits

See pricing for plan prices and monthly request limits. Each request counts as one call unless a route says otherwise.

• Free prices are delayed by 15 minutes. A delayed answer carries delayed: true.
• A futures price has no previous close, change or volume. A change across a contract roll would be false, so the API does not work one out.
• Prices and bars are the front month as it traded. They step on each roll day: CL stepped by about 4 dollars on 19 October 2026. Do not read that step as a one day move.
• market_session is open or closed by the contract's published hours. A closed series answers with its last price and is not stale. An open series is stale when its price is more than 15 minutes old.
• A daily bar is one trading day and appears at 00:00 UTC. On Free it appears 15 minutes later, and end comes back when that cut your range. Today's partial bar is never shown.
• One-minute bars are kept for 12 months, and one request covers at most 5 days. Free gets 403 plan_upgrade_required.
• A batch holds up to 50 ids and counts one call for each id that returns a price. An unknown id is listed in errors and is not counted.

Endpoints

Every route is a GET and needs your key in the Authorization: Bearer header. The examples show the shape of an answer, not live data.

Futures we price

GET /v1/futures

Every futures series we price, by id, with its name and unit. Read from our own list, so it is open to every plan and counts one call.

MCP: tool futures, action list.

Parameters

This route takes no parameters.

Response fields

curl -H "Authorization: Bearer $NARWHAL_API_KEY" \
  "https://api.narwhalapi.com/v1/futures"

{
  "futures": [
    {
      "id": "CL",
      "name": "WTI Crude Oil",
      "category": "energy",
      "exchange": "NYMEX",
      "currency": "USD",
      "unit": "usd_per_barrel"
    },
    {
      "id": "GC",
      "name": "Gold",
      "category": "metals",
      "exchange": "COMEX",
      "currency": "USD",
      "unit": "usd_per_troy_ounce"
    }
  ]
}

Latest price of one futures series

GET /v1/futures/{id}/price

The latest price. market_session is open or closed by the series' hours; a closed series answers with its last price, and stale is true only when an open series has no price from the last 15 minutes. Free sees the price 15 minutes late and the answer carries delayed: true. A futures price has no previous close, change or volume: the series is the front month joined end to end and not adjusted, so it has a gap on each roll day.

MCP: tool futures, action price.

Parameters

Response fields

curl -H "Authorization: Bearer $NARWHAL_API_KEY" \
  "https://api.narwhalapi.com/v1/futures/CL/price"

{
  "id": "CL",
  "name": "WTI Crude Oil",
  "exchange": "NYMEX",
  "currency": "USD",
  "unit": "usd_per_barrel",
  "price": "102.11",
  "market_session": "open",
  "timestamp": "2026-10-29T18:38:00Z",
  "stale": false
}

Latest prices for up to 50 futures series

GET /v1/futures/prices

Latest price of each listed id (Free sees them 15 minutes late). One call is counted for each id that returns a price, taken in one step: if fewer calls are left than ids that resolved, the whole request is refused with 429 quota_exceeded. Ids that return no price are listed in errors (as id) and cost nothing; if no id resolves the answer is still 200, with an empty prices. A futures price has no previous close, change or volume: the series is the front month joined end to end and not adjusted, so it has a gap on each roll day.

Send up to 50 ids. A batch is charged in one step: if you have fewer calls left than ids that resolve, the whole request returns 429 quota_exceeded.

MCP: tool futures, action prices.

Parameters

Response fields

curl -H "Authorization: Bearer $NARWHAL_API_KEY" \
  "https://api.narwhalapi.com/v1/futures/prices?ids=CL,GC,ES"

{
  "prices": [
    {
      "id": "CL",
      "name": "WTI Crude Oil",
      "exchange": "NYMEX",
      "currency": "USD",
      "unit": "usd_per_barrel",
      "price": "102.11",
      "market_session": "open",
      "timestamp": "2026-10-29T18:38:00Z",
      "stale": false
    },
    {
      "id": "GC",
      "name": "Gold",
      "exchange": "COMEX",
      "currency": "USD",
      "unit": "usd_per_troy_ounce",
      "price": "4021.3",
      "market_session": "open",
      "timestamp": "2026-10-29T18:38:00Z",
      "stale": false
    }
  ],
  "errors": [
    {
      "id": "XX",
      "code": "not_found"
    }
  ]
}

Price bars of one futures series

GET /v1/futures/{id}/bars

Daily (1d, one bar per trading day) or one-minute (1m) bars, oldest first. A day's bar is out at 00:00 UTC after the day (Free: 15 minutes later, and end comes back when that cut the range); today's partial bar is never shown. One-minute bars are for Basic and Pro (Free gets 403 plan_upgrade_required) and kept for 12 months. History: Free 12 months, Basic 5 years, Pro everything; start is sent back when the plan raised it. Up to 5,000 bars a page, with next_cursor. One call a page.

Bars are raw front month prices, so a bar can open away from the close before it on a roll day.

MCP: tool futures, action bars.

Parameters

Response fields

curl -H "Authorization: Bearer $NARWHAL_API_KEY" \
  "https://api.narwhalapi.com/v1/futures/ES/bars?interval=1d&start=2017-04-03&end=2017-04-05"

{
  "id": "ES",
  "currency": "USD",
  "bars": [
    {
      "timestamp": "2017-04-03T00:00:00Z",
      "open": "2357.5",
      "high": "2363.25",
      "low": "2340",
      "close": "2354.5"
    }
  ],
  "next_cursor": null
}

Errors

Errors use the shared problem shape with a request_id. See Errors and quota for the shape and the quota headers. Failed requests are not charged.