{"openapi":"3.1.0","info":{"title":"Commodity Futures Term Structure API","version":"1.0.0","description":"The shape of the commodity futures curve — contango versus backwardation — and the roll yield it pays, computed live from Yahoo Finance dated futures contracts, no key, nothing stored. A single commodity price hides the most important thing about it: what the market charges to hold it forward. When deferred contracts cost MORE than the front (an upward curve, contango) a long futures position bleeds money as it rolls up the curve each month; when they cost LESS (a downward curve, backwardation — classic for crude oil in tight markets) the roll pays you. That roll yield, not the spot move, is what drives the long-run return of commodity-index investing. This API reads the actual dated contracts — the front month and the deferred months out the curve — for crude oil, natural gas, gasoline, gold, silver, copper, corn, wheat and soybeans, and returns the full term structure, the front-to-second-month roll yield annualised, the curve shape and the front-vs-back spread. The curve endpoint returns one commodity's full chain; the screener endpoint ranks every commodity by roll yield, separating the backwardated markets (positive carry for a long) from the contango ones (negative carry). This is the commodity futures term-structure / roll-yield cut — distinct from the crypto dated-futures curve API, the inter-commodity crack/crush spread API, the commodity-momentum and seasonality APIs and the spot price feeds. It is the carry, read straight off the curve.","contact":{"name":"PremiumApi","url":"https://www.oanor.com/by/premiumapi"}},"servers":[{"url":"https://api.oanor.com/commoditycurve-api","description":"oanor gateway"}],"tags":[{"name":"Screener"},{"name":"Curve"},{"name":"Commodities"},{"name":"Meta"}],"components":{"securitySchemes":{"oanorKey":{"type":"apiKey","in":"header","name":"x-oanor-key","description":"Get your key at https://www.oanor.com/developer/keys"}}},"security":[{"oanorKey":[]}],"paths":{"/v1/screener":{"get":{"operationId":"get_v1_screener","tags":["Screener"],"summary":"Rank all commodities by roll yield, backwardation vs contango","description":"","parameters":[],"security":[{"oanorKey":[]}],"responses":{"200":{"description":"OK","content":{"application/json":{"example":{"data":{"note":"Commodities ranked by annualised front-to-second-month roll yield. Positive (backwardation) = a long futures position earns the roll; negative (contango) = it pays the roll away. The roll yield, not the spot move, drives long-run commodity-index returns. Read fresh per call, lightly cached.","count":9,"source":"Yahoo Finance","results":[{"name":"Crude Oil (WTI)","rank":1,"unit":"$/bbl","shape":"backwardation","available":true,"commodity":"oil","front_price":84.34,"front_vs_back_pct":5.68,"roll_yield_annualized_pct":22.47},{"name":"Gasoline RBOB","rank":2,"unit":"$/gal","shape":"backwardation","available":true,"commodity":"gasoline","front_price":2.9872,"front_vs_back_pct":14.26,"roll_yield_annualized_pct":20.8},{"name":"Gold","rank":3,"unit":"$/oz","shape":"flat","available":true,"commodity":"gold","front_price":4225.3,"front_vs_back_pct":-0.86,"roll_yield_annualized_pct":1.48},{"name":"Silver","rank":4,"unit":"$/oz","shape":"flat","available":true,"commodity":"silver","front_price":67.15,"front_vs_back_pct":-3.02,"roll_yield_annualized_pct":0.27},{"name":"Soybeans","rank":5,"unit":"cents/bu","shape":"contango","available":true,"commodity":"soybeans","front_price":1113.25,"front_vs_back_pct":-0.36,"roll_yield_annualized_pct":-5.37},{"name":"Corn","rank":6,"unit":"cents/bu","shape":"contango","available":true,"commodity":"corn","front_price":410.5,"front_vs_back_pct":-1.79,"roll_yield_annualized_pct":-10.77},{"name":"Wheat","rank":7,"unit":"cents/bu","shape":"contango","available":true,"commodity":"wheat","front_price":583,"front_vs_back_pct":-1.89,"roll_yield_annualized_pct":-11.36},{"name":"Natural Gas","rank":8,"unit":"$/MMBtu","shape":"contango","available":true,"commodity":"natgas","front_price":3.053,"front_vs_back_pct":-1.61,"roll_yield_annualized_pct":-13.99},{"name":"Copper","rank":9,"unit":"$/lb","shape":"contango","available":true,"commodity":"copper","front_price":6.253,"front_vs_back_pct":-4.01,"roll_yield_annualized_pct":-27.38}],"contango":["soybeans","corn","wheat","natgas","copper"],"unavailable":[],"backwardated":["oil","gasoline"],"most_contango":{"commodity":"copper","roll_yield":-27.38},"most_backwardated":{"commodity":"oil","roll_yield":22.47}},"meta":{"timestamp":"2026-06-12T10:34:33.799Z","request_id":"af2b5d27-cc91-43e7-b68a-864ca7ae4f76"},"status":"ok","message":"Commodity roll-yield screener retrieved successfully","success":true}}}},"401":{"description":"Missing or invalid x-oanor-key header"},"402":{"description":"Active subscription required"},"429":{"description":"Rate-limit or monthly quota reached"},"502":{"description":"Upstream did not respond"}}}},"/v1/curve":{"get":{"operationId":"get_v1_curve","tags":["Curve"],"summary":"One commodity's full dated futures curve, roll yield and shape","description":"","parameters":[{"name":"commodity","in":"query","required":true,"description":"Commodity key: oil, natgas, gold, copper, corn, ...","schema":{"type":"string"},"example":"oil"}],"security":[{"oanorKey":[]}],"responses":{"200":{"description":"OK","content":{"application/json":{"example":{"data":{"name":"Crude Oil (WTI)","note":"The dated futures curve for Crude Oil (WTI). roll_yield_annualized_pct is the front-vs-second-month difference annualised: positive = backwardation (a long roll earns it), negative = contango (a long roll pays it away). front_vs_back_pct compares the front to the most-deferred contract. Read fresh per call, lightly cached.","read":"backwardation — front richer than deferred; a long futures roll EARNS 22.5%/yr (tight market)","unit":"$/bbl","curve":[{"price":84.34,"expiry":"2026-07","contract":"CLN26.NYM"},{"price":82.79,"expiry":"2026-08","contract":"CLQ26.NYM"},{"price":81.35,"expiry":"2026-09","contract":"CLU26.NYM"},{"price":79.81,"expiry":"2026-10","contract":"CLV26.NYM"},{"price":78.5,"expiry":"2026-11","contract":"CLX26.NYM"},{"price":77.3,"expiry":"2026-12","contract":"CLZ26.NYM"},{"price":76.32,"expiry":"2027-01","contract":"CLF27.NYM"},{"price":75.24,"expiry":"2027-02","contract":"CLG27.NYM"},{"price":74.93,"expiry":"2027-03","contract":"CLH27.NYM"},{"price":74.24,"expiry":"2027-04","contract":"CLJ27.NYM"},{"price":73.77,"expiry":"2027-05","contract":"CLK27.NYM"}],"shape":"backwardation","source":"Yahoo Finance (dated CL futures)","commodity":"oil","contracts":11,"front_month":{"price":84.34,"expiry":"2026-07","contract":"CLN26.NYM"},"second_month":{"price":82.79,"expiry":"2026-08","contract":"CLQ26.NYM"},"front_vs_back_pct":14.33,"roll_yield_annualized_pct":22.47},"meta":{"timestamp":"2026-06-12T10:34:34.013Z","request_id":"f76fac22-167d-4859-869c-620da9df8115"},"status":"ok","message":"Commodity futures curve retrieved successfully","success":true}}}},"401":{"description":"Missing or invalid x-oanor-key header"},"402":{"description":"Active subscription required"},"429":{"description":"Rate-limit or monthly quota reached"},"502":{"description":"Upstream did not respond"}}}},"/v1/commodities":{"get":{"operationId":"get_v1_commodities","tags":["Commodities"],"summary":"The supported commodity futures and their roots","description":"","parameters":[],"security":[{"oanorKey":[]}],"responses":{"200":{"description":"OK","content":{"application/json":{"example":{"data":{"note":"The commodity futures the term-structure curve covers. Pass commodity= to /v1/curve.","count":9,"source":"Yahoo Finance","commodities":[{"name":"Crude Oil (WTI)","root":"CL","unit":"$/bbl","exchange":"NYM","commodity":"oil"},{"name":"Natural Gas","root":"NG","unit":"$/MMBtu","exchange":"NYM","commodity":"natgas"},{"name":"Gasoline RBOB","root":"RB","unit":"$/gal","exchange":"NYM","commodity":"gasoline"},{"name":"Gold","root":"GC","unit":"$/oz","exchange":"CMX","commodity":"gold"},{"name":"Silver","root":"SI","unit":"$/oz","exchange":"CMX","commodity":"silver"},{"name":"Copper","root":"HG","unit":"$/lb","exchange":"CMX","commodity":"copper"},{"name":"Corn","root":"ZC","unit":"cents/bu","exchange":"CBT","commodity":"corn"},{"name":"Wheat","root":"ZW","unit":"cents/bu","exchange":"CBT","commodity":"wheat"},{"name":"Soybeans","root":"ZS","unit":"cents/bu","exchange":"CBT","commodity":"soybeans"}]},"meta":{"timestamp":"2026-06-12T10:34:34.092Z","request_id":"67b1468d-59f4-43dd-87de-6ce5d89cfe82"},"status":"ok","message":"Commodities retrieved successfully","success":true}}}},"401":{"description":"Missing or invalid x-oanor-key header"},"402":{"description":"Active subscription required"},"429":{"description":"Rate-limit or monthly quota reached"},"502":{"description":"Upstream did not respond"}}}},"/v1/meta":{"get":{"operationId":"get_v1_meta","tags":["Meta"],"summary":"Service metadata","description":"","parameters":[],"security":[{"oanorKey":[]}],"responses":{"200":{"description":"OK","content":{"application/json":{"example":{"data":{"note":"commodity is one of /v1/commodities keys (oil, natgas, gold, copper, corn, ...). The chain is built from the current month forward; skip-month commodities return fewer contracts. roll_yield_annualized_pct > 0 = backwardation (long roll earns), < 0 = contango (long roll pays). A 30-minute protective cache fronts the shared Yahoo upstream.","source":"Yahoo Finance dated futures contracts, live","service":"commoditycurve-api","endpoints":{"GET /v1/meta":"This document.","GET /v1/curve":"One commodity's full dated futures curve, roll yield and shape (commodity=oil).","GET /v1/screener":"Rank all commodities by roll yield, backwardation vs contango.","GET /v1/commodities":"The supported commodity futures and their roots."},"commodities":["oil","natgas","gasoline","gold","silver","copper","corn","wheat","soybeans"],"description":"Commodity futures term structure & roll yield — the shape of the futures curve (contango vs backwardation) and the roll yield it pays, live from Yahoo Finance dated futures contracts (no key, nothing stored). curve returns one commodity's full dated chain with the front-to-second-month roll yield annualised, the curve shape and front-vs-back spread; screener ranks crude oil, natural gas, gasoline, gold, silver, copper, corn, wheat and soybeans by roll yield, separating the backwardated (positive carry) from the contango (negative carry) markets. The commodity futures term-structure / roll-yield cut — distinct from the crypto dated-futures curve API, the crack/crush inter-commodity spread API, the commodity-momentum and seasonality APIs and the spot price feeds.","upstream_status":"ok","most_backwardated":"oil"},"meta":{"timestamp":"2026-06-12T10:34:34.164Z","request_id":"d25cc09e-7331-4d88-8485-f20edac0f987"},"status":"ok","message":"Meta","success":true}}}},"401":{"description":"Missing or invalid x-oanor-key header"},"402":{"description":"Active subscription required"},"429":{"description":"Rate-limit or monthly quota reached"},"502":{"description":"Upstream did not respond"}}}}},"x-oanor-pricing":[{"slug":"free","name":"Free","price_cents_month":0,"monthly_call_quota":715,"rps_limit":2,"hard_limit":true},{"slug":"starter","name":"Starter","price_cents_month":1190,"monthly_call_quota":16600,"rps_limit":6,"hard_limit":true},{"slug":"pro","name":"Pro","price_cents_month":3520,"monthly_call_quota":89000,"rps_limit":16,"hard_limit":true},{"slug":"mega","name":"Mega","price_cents_month":7940,"monthly_call_quota":498000,"rps_limit":40,"hard_limit":true}],"x-oanor-marketplace-url":"https://www.oanor.com/api/commoditycurve-api"}