FuturesAPI Documentation

API Key

Get Started

First, register to receive an API key.

  Base URL: api.futures-api.com
  Authorization:
    => HTTP Headers
      => x-api-key = {YOUR_API_TOKEN}

Example

Using Axios and NodeJS...

  const res = await axios.get(
  'api.futures-api.com/last', 
    {
      params: { symbol: 'CL' } 
      headers: {
          'x-api-key': "{YOUR_API_TOKEN}"
      }
    }
  )
  return res.data

Common Parameters

Dates

string

  Format: YYYY-MM-DD
  Example: "2021-01-12"

Symbols

string

  Format: XX
  Example: "CL"

See the Supported Symbols endpoint for all supported symbols

Month

number

  Format: 0
  Example: 10

Months are zero-index. January is month 0 and December is month 11.

Format

string

  Options: "csv", "json"
  Example: "json"

Due to the nature of CSV being strict row format, CSV requests will not return associated metadata for any request.

Offset

number

  Format: XXX
  Example: 500

Endpoints marked as "Return Limited" will only return 100 objects per request. Use the <offset> parameter to paginate results.

Latest Contracts for Symbol

This endpoint returns each of the latest futures contracts for a given symbol for the next twelve months.

Use the optional <month> parameter to return the latest contract for a given month.

Input

  Method: GET
  Path: /last
  Parameters:
   symbol: string required
   month: number
   format: string

Response

   {
      metadata: {
        symbol: string;
        name: string;
        exchange: string;
      },
      data: [{
          date: string;
          symbol: string;
          month: number;
          year: number;
          last: number;
          open: number;
          high: number;
          low: number;
          change: number;
          change_p: number;
       }]
    }

Example

Using Axios and NodeJS...

Call

  const res = await axios.get(
  'api.futures-api.com/last', 
    {
      params: { symbol:   'CL' } 
      headers: {
          'x-api-key': {YOUR_API_TOKEN}
      }
    }
  )
  return res.data

Response

  {
      "metadata": {
        "symbol": "CL",
        "name": "WTI Crude Oil",
        "exchange": "NYMEX"
    },
    "data": [
        {
           "date": "2022-07-01",
           "symbol": "CL",
            "month": 7,
            "year": 2022,
            "last": 108.42,
            "open": 106.01,
            "high": 109.34,
            "low": 104.56,
            "change": 1.11
            "change_p": 0.02515
        },
        {
            "date": "2022-07-01",
            "symbol": "CL",
            "month": 8,
            "year": 2022,
            "last": 105.38,
            "open": 103.33,
            "high": 106.26,
            "low": 101.94,
            "change": 1.76
            "change_p": 0.2211
        },
        ...
    ]
    ...
  }

Time Series

✴ Return Limited: 100 Objects
✴ Earliest Date: 2006-01-01 for most assets

This endpoint returns futures contracts over a specified date range for a given symbol. Use this endpoint for historical data.

The <to> parameter is optional. Not specifying this parameter will return all contracts between the given <from> parameter and the latest available date.

Use the optional <month> and <year> parameters to get a specific month, year, or month and year contract over the given period of time.
‍

Input

  Method: GET
  Path: /time-series
  Parameters:
   symbol: string required
   from: string required
   to: string
   month: number
   year: number
   offset: number
   format: string

Response

   {
      metadata: {
        symbol: string;
        name: string;
        exchange: string;
      },
      data: [{
          date: string;
          symbol: string;
          month: number;
          year: number;
          last: number;
          open: number;
          high: number;
          low: number;
          change: number;
          change_p: number;
       	}]
    }

Example

Using Axios and NodeJS...

Call

  const res = await axios.get(
  'api.futures-api.com/time-series', 
    {
      params: { 
        symbol: 'CL',
        from: '2010-01-03'
        to: '2011-01-03'
      } 
      headers: {
          'x-api-key': {YOUR_API_TOKEN}
      }
    }
  )
  return res.data

Response

  {
      "metadata": {
        "symbol": "CL",
        "name": "WTI Crude Oil",
        "exchange": "NYMEX"
    },
    "data": [
        {
           "date": "2010-01-03",
           "symbol": "CL",
            "month": 7,
            "year": 2022,
            "last": 108.42,
            "open": 106.01,
            "high": 109.34,
            "low": 104.56,
            "change": 2.01
            "change_p": 0.02515
        },
        {
            "date": "2010-01-03",
            "symbol": "CL",
            "month": 8,
            "year": 2022,
            "last": 105.38,
            "open": 103.33,
            "high": 106.26,
            "low": 101.94,
            "change": 2.01
            "change_p": 0.02211
        },
        ...
    ]
    ...
  }

Days From Date

✴ Return Limited: 100 Objects
✴ Oldest Date: 2006-01-01

This endpoint returns futures contracts for the date falling on the number of days from the date you specified. This is useful for getting contracts closest to a date without having to determine the last date the contract was traded.

Consider wanting contracts for WTI Crude that were traded 30 days before December 25, 2021. With Thanksgiving in the US being November 25, which date were contracts last traded? This can be hard to determine so we take the guess work out.

Specifying the <dateFrom> parameter as "2021-12-25" and the <daysFrom> parameter as 30 returns the contracts traded on the date that is less-than-or-equal-to 30 days from the <dateFrom> parameter i.e. the date closest to 30 days ago.

Use the optional <month> parameter to get a specific month contract.

Use the optional <inPast> parameter to specify if <daysFrom> should be added or subtracted from <dateFrom>. Setting <inPast> to false will result in contracts that fall after the given date. Default is true.

‍

Input

  Method: GET
  Path: /days-from
  Parameters:
   symbol: string required
   dateFrom: string required
   daysFrom: string required
   inPast: boolean default: true
   month: number
   offset: number
   format: string default: 'json'

Response

   {
      metadata: {
        symbol: string;
        name: string;
        exchange: string;
      },
      data: [{
          date: string;
          symbol: string;
          month: number;
          year: number;
          last: number;
          open: number;
          high: number;
          low: number;
          change: number;
          change_p: number;
       	}]
    }

Example

Using Axios and NodeJS...

Call

  const res = await axios.get(
  'api.futures-api.com/days-from', 
    {
      params: { 
        symbol: 'CL',
        dateFrom: '2021-12-25'
        daysFrom: 30
      } 
      headers: {
          'x-api-key': {YOUR_API_TOKEN}
      }
    }
  )
  return res.data

Response

  {
      "metadata": {
        "symbol": "CL",
        "name": "WTI Crude Oil",
        "exchange": "NYMEX"
    },
    "data": [
        {
           "date": "2021-11-24",
           "symbol": "CL",
            "month": 0,
            "year": 2022,
            "last": 108.42,
            "open": 106.01,
            "high": 109.34,
            "low": 104.56,
            "change": 2.01
            "change_p": 0.02515
        },
        {
            "date": "2021-11-24",
            "symbol": "CL",
            "month": 1,
            "year": 2022,
            "last": 105.38,
            "open": 103.33,
            "high": 106.26,
            "low": 101.94,
            "change": 2.01
            "change_p": 0.02211
        },
        ...
    ]
    ...
  }

Supported Assets

This endpoint returns all symbols supported by the last and time-series endpoint.

Input

  Method: GET
  Path: /symbols
  Parameters:
  format: string

Response

   [
      {
      	symbol: string;
        name: string;
        exchange: string;
      }
   ]

Example

Using Axios and NodeJS...

Call

  const res = await axios.get(
  'api.futures-api.com/symbols', 
    {
      headers: {
          'x-api-key': {YOUR_API_TOKEN}
      }
    }
  )
  return res.data

Response

  [
    {
        "symbol": "RS",
        "name": "Canola",
        "exchange": "ICEUS"
    },
    {
        "symbol": "PA",
        "name": "Palladium",
        "exchange": "NYMEX"
    },
    {
        "symbol": "NG",
        "name": "Natural Gas (US)",
        "exchange": "NYMEX"
    },
    ...
  ]

Support

Hours of Support: 8AM-6PM EST Monday-Friday

Email: support@futures-api.com