futures conversion

Returns conversion parameters for translating a supported spot/index or ETF ticker onto its corresponding futures scale.

GET/futures/conversionClassic Tier

Returns conversion parameters for translating a supported spot/index or ETF ticker onto its corresponding futures scale. The service fits the terms on request from the most recent 30 matched 1-minute spot and futures points and caches the result for 10 minutes. When the current session has fewer than 30 matched minutes, the service fills the window from the end of the previous trading day. The service needs at least 10 matched minutes; otherwise it returns 404.

Every pair accepts the additive, multiplicative and affine models. The default is additive for a cash index and affine for an ETF. Any active gexbot data subscription (Classic, State, Orderflow or Quant) can call this endpoint. Send a gexbot API key in the Authorization header. A Research API key is not accepted.

Supported Pairs

Source Ticker	Target Future	Default Model
`SPX`	`ES`	`additive`
`SPY`	`ES`	`affine`
`NDX`	`NQ`	`additive`
`QQQ`	`NQ`	`affine`
`RUT`	`RTY`	`additive`
`IWM`	`RTY`	`affine`
`DIA`	`YM`	`affine`
`GLD`	`GC`	`affine`
`SLV`	`SI`	`affine`
`USO`	`CL`	`affine`

Request

Example: /futures/conversion?ticker=SPX&future=ES&model=additive

Headers

Name	Type	Description
`Authorization`	`string`	Required. Format: "Bearer <YOUR_API_KEY>"
`User-Agent`	`string`	Required. Identify your client application.
`Accept`	`string`	Required. Set to "application/json".

Query Parameters

Name	Type	Required	Description
`ticker`	`string`	Yes	Source ticker to convert from (e.g. `SPX`, `SPY`, `NDX`, `QQQ`, `RUT`, `IWM`, `DIA`, `GLD`, `SLV`, `USO`).
`future`	`string`	Yes	Futures product code to convert to (e.g. `ES`, `NQ`, `RTY`, `YM`, `GC`, `SI`, `CL`).
`model`	`string`	No	Conversion model: `additive`, `multiplicative`, or `affine`. Defaults to `additive` for `SPX`, `NDX`, and `RUT`. Defaults to `affine` for ETF and equity source tickers.

Response

Field	Type	Description
`future_contract`	`string`	The active futures contract selected for the requested product, such as `ESU6`.
`multiplier`	`number`	Multiplier for converting spot price and strikes to the respective futures scale.
`additive`	`number`	Additive offset for converting spot price and strikes to the respective futures scale.

{
  "future_contract": "ESU6",
  "multiplier": 1,
  "additive": 12.345
}

{
  "type": "object",
  "properties": {
    "future_contract": {
      "type": "string",
      "description": "The active futures contract selected for the requested product."
    },
    "multiplier": {
      "type": "number",
      "format": "double",
      "description": "Multiplier for converting spot price and strikes to the respective futures scale."
    },
    "additive": {
      "type": "number",
      "format": "double",
      "description": "Additive offset for converting spot price and strikes to the respective futures scale."
    }
  },
  "required": ["future_contract", "multiplier", "additive"],
  "additionalProperties": false
}

type: object
properties:
  future_contract:
    type: string
    description: The active futures contract selected for the requested product.
  multiplier:
    type: number
    format: double
    description: Multiplier for converting spot price and strikes to the respective futures scale.
  additive:
    type: number
    format: double
    description: Additive offset for converting spot price and strikes to the respective futures scale.
required: [future_contract, multiplier, additive]
additionalProperties: false

Errors

Status	When	Example body
`400`	Missing or unknown `ticker` or `future`, a synthetic futures source ticker such as `ES_SPX`, an unsupported pair, an invalid `model`, a missing `User-Agent` header, or a missing `Authorization` header.	`{"error": "Unsupported futures conversion pair: SPX/NQ."}` or `{"error": "Synthetic futures tickers are not valid futures conversion source tickers."}`
`401`	The API key is not valid.	(no body)
`403`	The key is not a gexbot API key (no body), or the account has no active Classic or higher subscription.	`{"error": "User does not have permission to access this endpoint."}`
`404`	No spot data, no futures bars, no active contract, or fewer than 10 matched minutes are available. This can occur outside market hours.	`{"error": "No spot data available for conversion window."}` or, for `GC`, `SI` and `CL`, `{"error": "No active futures contract found for product."}`
`429`	The account exceeded its daily or monthly quota for this endpoint.	`{"error": "Rate limit exceeded."}`
`503`	The upstream futures data source did not answer, or another request is refreshing the same pair. Retry after a few seconds.	`{"error": "Futures conversion is currently being refreshed. Try again shortly."}`