# Commodities API
> Live commodity futures prices as an API — the energy, grain, soft and livestock commodity complex, served from Yahoo Finance. For any commodity it returns the front-month futures price, the previous close, the absolute and percentage change on the day, the day's high and low and the 52-week high and low, with the price's currency and quoting unit (e.g. USD per barrel, US cents per bushel). Look a commodity up by name or alias (crude oil, Brent, natural gas, gasoline, corn, wheat, soybeans, coffee, sugar, cocoa, cotton, orange juice, live cattle, lean hogs and more), pull a category board (energy, grains, softs, livestock) ranked by the day's move, or get the whole board in one call. The commodity-quote layer for trading, markets and dashboard apps. Live, no key. Distinct from the precious-metals API — this is the energy, agricultural and soft-commodity complex.

## Authentication
All requests require your oanor API key in the `x-oanor-key` header. Get one at https://www.oanor.com/developer/keys.

```bash
curl -H "x-oanor-key: oanor_live_…" "https://api.oanor.com/commodities-api/..."
```

## Pricing
- **Free** (Free) — 10,000 calls/Mo, 4 req/s
- **Starter** ($9/Mo) — 135,000 calls/Mo, 12 req/s
- **Pro** ($23/Mo) — 680,000 calls/Mo, 35 req/s
- **Desk** ($54/Mo) — 3,400,000 calls/Mo, 100 req/s

## Endpoints

### Commodity

#### `GET /v1/commodity` — One commodity futures quote

**Parameters:**
- `commodity` (query, required, string) — Commodity key or alias (e.g. wti, natgas, corn, coffee, oil, gas) Example: `wti`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/commodities-api/v1/commodity?commodity=wti"
```

**Response:**
```json
{
    "data": {
        "name": "Crude Oil (WTI)",
        "unit": "barrel",
        "as_of": "2026-06-09T02:52:20.000Z",
        "price": 90.65,
        "quote": "USD per barrel",
        "change": -0.65,
        "symbol": "CL=F",
        "day_low": 90.48,
        "category": "energy",
        "currency": "USD",
        "day_high": 91.55,
        "commodity": "wti",
        "change_pct": -0.71,
        "week52_low": 54.98,
        "week52_high": 119.48,
        "previous_close": 91.3
    },
    "meta": {
        "timestamp": "2026-06-09T03:02:25.913Z",
        "request_id": "2744de19-7a5e-4d07-9812-6e439c7311c0"
    },
    "status": "ok",
    "message": "Commodity retrieved successfully",
    "success": true
}
```

### Category

#### `GET /v1/category` — A category board ranked by day change

**Parameters:**
- `category` (query, required, string) — Category: energy|grains|softs|livestock Example: `energy`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/commodities-api/v1/category?category=energy"
```

**Response:**
```json
{
    "data": {
        "count": 5,
        "category": "energy",
        "commodities": [
            {
                "name": "Natural Gas",
                "unit": "MMBtu",
                "as_of": "2026-06-09T02:51:54.000Z",
                "price": 3.15,
                "quote": "USD per MMBtu",
                "change": 0.01,
                "symbol": "NG=F",
                "day_low": 3.13,
                "category": "energy",
                "currency": "USD",
                "day_high": 3.15,
                "commodity": "natgas",
                "change_pct": 0.16,
                "week52_low": 2.48,
                "week52_high": 7.83,
                "previous_close": 3.15
            },
            {
                "name": "RBOB Gasoline",
                "unit": "gallon",
                "as_of": "2026-06-09T02:52:08.000Z",
                "price": 3.01,
                "quote": "USD per gallon",
                "change": -0.01,
                "symbol": "RB=F",
                "day_low": 3.01,
                "category": "energy",
                "currency": "USD",
                "day_high": 3.02,
                "commodity": "gasoline",
                "change_pct": -0.33,
                "week52_low": 1.67,
                "week52_high": 3.82,
                "previous_close": 3.02
            },
            {
                "name": "Brent Crude Oil",
                "unit": "barrel",
                "as_of": "2026-06-09T02:50:58.000Z",
                "
…(truncated, see openapi.json for full schema)
```

### List

#### `GET /v1/list` — Whole commodity board in one call

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/commodities-api/v1/list"
```

**Response:**
```json
{
    "data": {
        "count": 19,
        "commodities": [
            {
                "name": "Orange Juice",
                "unit": "lb",
                "as_of": "2026-06-08T17:59:14.000Z",
                "price": 164,
                "quote": "US cents per lb",
                "change": 3.4,
                "symbol": "OJ=F",
                "day_low": 154,
                "category": "softs",
                "currency": "USX",
                "day_high": 168.25,
                "commodity": "orangejuice",
                "change_pct": 2.12,
                "week52_low": 132.5,
                "week52_high": 344.3,
                "previous_close": 160.6
            },
            {
                "name": "Cotton",
                "unit": "lb",
                "as_of": "2026-06-08T15:30:26.000Z",
                "price": 77.87,
                "quote": "US cents per lb",
                "change": 0.39,
                "symbol": "CT=F",
                "day_low": 84.37,
                "category": "softs",
                "currency": "USX",
                "day_high": 87.36,
                "commodity": "cotton",
                "change_pct": 0.5,
                "week52_low": 60.71,
                "week52_high": 88.88,
                "previous_close": 77.48
            },
            {
                "name": "Sugar No.11",
                "unit": "lb",
                "as_of": "2026-06-08T16:59:59.000Z",
                "price": 14.16,
                "quote": "
…(truncated, see openapi.json for full schema)
```

### Meta

#### `GET /v1/meta` — Service metadata and full commodity list

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/commodities-api/v1/meta"
```

**Response:**
```json
{
    "data": {
        "source": "Yahoo Finance public chart API (live)",
        "service": "commodities-api",
        "endpoints": {
            "GET /v1/list": "The whole commodity board in one call.",
            "GET /v1/meta": "This document (with the full commodity list).",
            "GET /v1/category": "A category board ranked by day change (category=energy|grains|softs|livestock).",
            "GET /v1/commodity": "One commodity quote (commodity=wti|natgas|corn|coffee|… or aliases like oil, gas)."
        },
        "categories": [
            "energy",
            "grains",
            "softs",
            "livestock"
        ],
        "commodities": {
            "wti": "Crude Oil (WTI)",
            "corn": "Corn",
            "oats": "Oats",
            "brent": "Brent Crude Oil",
            "cocoa": "Cocoa",
            "sugar": "Sugar No.11",
            "wheat": "Wheat",
            "coffee": "Coffee",
            "cotton": "Cotton",
            "natgas": "Natural Gas",
            "gasoline": "RBOB Gasoline",
            "leanhogs": "Lean Hogs",
            "soybeans": "Soybeans",
            "heatingoil": "Heating Oil",
            "livecattle": "Live Cattle",
            "soybeanoil": "Soybean Oil",
            "orangejuice": "Orange Juice",
            "soybeanmeal": "Soybean Meal",
            "feedercattle": "Feeder Cattle"
        },
        "description": "Live commodity futures prices from Yahoo Finance: for any energy, grain, soft or livestoc
…(truncated, see openapi.json for full schema)
```


---
Marketplace page: https://www.oanor.com/api/commodities-api
OpenAPI spec: https://www.oanor.com/api/commodities-api/openapi.json