Spreads & Margins

Premium analytics endpoints for crack spreads, basis, refinery margin, curve structure, and physical premiums.

Entitlement Caveat

The live issue list records a backend entitlement bug for /v1/spreads/*: some enterprise keys can receive 403 because the gate reads a stale plan field. This page documents the intended customer surface; verify your production key before launch.

Endpoints

FamilyEndpoints
Crack spreads/v1/spreads/crack, /historical, /all
Basis/v1/spreads/basis, /historical, /all
Margins/v1/spreads/margin, /historical, /all
Curve structure/v1/spreads/curve-structure, /all
Physical premium/v1/spreads/physical-premium, /historical, /all

Common Parameters

ParameterTypeDescription
codestringSpread or market code where supported
datedateSnapshot date
from, todateHistorical range
limitintegerMaximum records

Common Response Shape

{
  "status": "success",
  "data": [
    {
      "code": "WTI_321_CRACK",
      "value": 24.15,
      "currency": "USD",
      "unit": "barrel",
      "period": "2026-07-15",
      "updated_at": "2026-07-15T14:30:00.000Z"
    }
  ]
}

Error Cases

StatusWhen
400Missing or invalid query parameter
401Missing or invalid API key
403Premium analytics entitlement missing
402Plan/quota issue

Data Rights

Spreads are derived analytics. Public display, redistribution, or downstream resale requires review under the Data Usage Policy.

Last Updated: