# OilPriceAPI — Full Technical Reference for AI Agents

> Base URL: https://api.oilpriceapi.com
> Authentication: `Authorization: Token YOUR_API_KEY`
> OpenAPI Spec: https://api.oilpriceapi.com/api-docs
> MCP Server: https://www.npmjs.com/package/oilpriceapi-mcp
> Website: https://www.oilpriceapi.com
> Docs: https://docs.oilpriceapi.com

This document enables an AI agent to authenticate, make API calls, parse responses, and handle errors for the OilPriceAPI platform. The catalog spans crude oil, natural gas, refined products, coal, LNG, marine fuels, carbon allowances, precious metals, forex, drilling intelligence, and futures. Exact availability varies by plan, source, and account entitlement.

Latest available values include source timestamps; refresh cadence varies by source, market hours, dataset, and plan. OilPriceAPI sells API access, normalization, monitoring, and delivery. Standard plans do not grant ownership of underlying source data or unrestricted raw-data redistribution rights. Data usage policy: https://www.oilpriceapi.com/legal/data-usage. Reviewed public facts: https://www.oilpriceapi.com/product-facts.json

---

## Authentication

All authenticated endpoints require an API key passed in the `Authorization` header:

```
Authorization: Token YOUR_API_KEY
```

New accounts start with a 7-day, 10,000-request core commodity API trial with no credit card. After the trial, the Free plan includes 200 requests per month. Dataset access and limits vary by source, plan, and account entitlement: https://www.oilpriceapi.com/auth/signup

The demo endpoint requires no authentication.

---

## Endpoints

### 1. Demo Prices (No Auth Required)

**GET /v1/demo/prices**

Returns a sample of current commodity prices. No API key needed.

```bash
curl https://api.oilpriceapi.com/v1/demo/prices
```

Response:

```json
{
  "status": "success",
  "data": {
    "prices": [
      {
        "price": 78.41,
        "code": "BRENT_CRUDE_USD",
        "created_at": "2026-03-09T12:00:00.000Z",
        "currency": "USD",
        "formatted": "$78.41",
        "type": "spot_price"
      }
    ]
  }
}
```

### 2. Latest Price for a Commodity

**GET /v1/prices/latest?by_code=CODE**

Returns the most recent price for a specific commodity.

```bash
curl -H "Authorization: Token YOUR_API_KEY" \
  "https://api.oilpriceapi.com/v1/prices/latest?by_code=BRENT_CRUDE_USD"
```

Response:

```json
{
  "status": "success",
  "data": {
    "price": 78.41,
    "code": "BRENT_CRUDE_USD",
    "created_at": "2026-03-09T12:00:00.000Z",
    "currency": "USD",
    "formatted": "$78.41",
    "type": "spot_price"
  }
}
```

### 3. All Latest Prices

**GET /v1/prices/all**

Returns the latest price for every commodity.

```bash
curl -H "Authorization: Token YOUR_API_KEY" \
  "https://api.oilpriceapi.com/v1/prices/all"
```

Response:

```json
{
  "status": "success",
  "data": {
    "prices": [
      {
        "price": 78.41,
        "code": "BRENT_CRUDE_USD",
        "created_at": "2026-03-09T12:00:00.000Z",
        "currency": "USD",
        "formatted": "$78.41",
        "type": "spot_price"
      },
      {
        "price": 72.01,
        "code": "WTI_USD",
        "created_at": "2026-03-09T12:00:00.000Z",
        "currency": "USD",
        "formatted": "$72.01",
        "type": "spot_price"
      }
    ]
  }
}
```

### 4. Batch Prices (Recommended for Multiple Commodities)

**POST /v1/prices/batch**

Fetch latest prices for multiple commodity codes in a single request. This is the most efficient way to get multiple prices and the recommended approach for AI agents.

```bash
curl -X POST \
  -H "Authorization: Token YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"codes": ["BRENT_CRUDE_USD", "WTI_USD", "NATURAL_GAS_USD"]}' \
  "https://api.oilpriceapi.com/v1/prices/batch"
```

Response:

```json
{
  "status": "success",
  "data": {
    "prices": [
      {
        "price": 78.41,
        "code": "BRENT_CRUDE_USD",
        "created_at": "2026-03-09T12:00:00.000Z",
        "currency": "USD",
        "formatted": "$78.41",
        "type": "spot_price"
      },
      {
        "price": 72.01,
        "code": "WTI_USD",
        "created_at": "2026-03-09T12:00:00.000Z",
        "currency": "USD",
        "formatted": "$72.01",
        "type": "spot_price"
      },
      {
        "price": 4.12,
        "code": "NATURAL_GAS_USD",
        "created_at": "2026-03-09T12:00:00.000Z",
        "currency": "USD",
        "formatted": "$4.12",
        "type": "spot_price"
      }
    ]
  }
}
```

### 5. Commodities List

**GET /v1/commodities**

Returns all supported commodity codes with metadata (currency, unit, category).

```bash
curl -H "Authorization: Token YOUR_API_KEY" \
  "https://api.oilpriceapi.com/v1/commodities"
```

### 6. Historical Prices

**GET /v1/prices/past_day?by_code=CODE**
**GET /v1/prices/past_week?by_code=CODE**
**GET /v1/prices/past_month?by_code=CODE**
**GET /v1/prices/past_year?by_code=CODE**

Returns historical price data for a specific commodity over the given time range.

```bash
curl -H "Authorization: Token YOUR_API_KEY" \
  "https://api.oilpriceapi.com/v1/prices/past_week?by_code=BRENT_CRUDE_USD"
```

---

## Complete Commodity Code Reference

### Crude Oil

| Code | Description |
|------|-------------|
| BRENT_CRUDE_USD | ICE Brent front-month (global benchmark) |
| WTI_USD | NYMEX WTI (Cushing, OK delivery) |
| DUBAI_CRUDE_USD | Dubai/Oman crude (Asia benchmark) |
| OPEC_BASKET_USD | OPEC Reference Basket |
| URALS_CRUDE_USD | Russian Urals crude |
| WCS_CRUDE_USD | Western Canadian Select |
| TAPIS_CRUDE_USD | Malaysian Tapis crude |
| MARS_USD | Mars US Gulf sour crude |
| LOUISIANA_LIGHT_USD | Louisiana Light Sweet crude |
| ANS_WEST_COAST_USD | Alaska North Slope (West Coast) |
| AZERI_LIGHT_USD | Azeri Light (Caspian/Mediterranean benchmark) |
| BASRAH_MEDIUM_USD | Iraqi Basrah Medium crude |
| BASRAH_HEAVY_USD | Iraqi Basrah Heavy crude |

### Natural Gas

| Code | Description |
|------|-------------|
| NATURAL_GAS_USD | Henry Hub (US benchmark, USD/MMBtu) |
| DUTCH_TTF_EUR | Dutch TTF (European benchmark, EUR/MWh) |
| DUTCH_TTF_NATURAL_GAS_USD | Dutch TTF in USD |
| NATURAL_GAS_GBP | UK NBP gas (pence/therm) |
| NATURAL_GAS_WAHA | Waha Hub (Permian Basin, USD/MMBtu) |
| JKM_LNG_USD | Japan Korea Marker LNG (Asian benchmark) |

### Refined Products

| Code | Description |
|------|-------------|
| GASOLINE_USD | Conventional gasoline |
| GASOLINE_RBOB_USD | RBOB Gasoline (reformulated) |
| DIESEL_USD | Ultra-low sulfur diesel |
| ULSD_DIESEL_USD | ULSD diesel (heating oil grade) |
| JET_FUEL_USD | Jet fuel / kerosene |
| HEATING_OIL_USD | No. 2 heating oil |
| PROPANE_MONT_BELVIEU_USD | Propane (Mont Belvieu hub) |
| ETHANOL_USD | Fuel ethanol |

### Chemicals & Petrochemicals

| Code | Description |
|------|-------------|
| AMMONIA_USD | Ammonia (USD/ton) |
| ASPHALT_USD | Asphalt (USD/ton) |
| BIODIESEL_USD | Biodiesel (USD/gallon) |
| ETHYLENE_USD | Ethylene (USD/ton) |
| METHANOL_USD | Methanol (USD/gallon) |
| NAPHTHA_USD | Naphtha (USD/barrel) |
| POLYETHYLENE_USD | Polyethylene (USD/ton) |
| POLYPROPYLENE_USD | Polypropylene (USD/ton) |
| UREA_USD | Urea (USD/ton) |

### US Retail Diesel (by Region)

| Code | Description |
|------|-------------|
| DIESEL_RETAIL_USD | US national average retail diesel |
| DIESEL_RETAIL_EAST_COAST_USD | East Coast retail diesel |
| DIESEL_RETAIL_MIDWEST_USD | Midwest retail diesel |
| DIESEL_RETAIL_GULF_COAST_USD | Gulf Coast retail diesel |
| DIESEL_RETAIL_ROCKY_MOUNTAIN_USD | Rocky Mountain retail diesel |
| DIESEL_RETAIL_WEST_COAST_USD | West Coast retail diesel |
| DIESEL_RETAIL_CALIFORNIA_USD | California retail diesel |

### Marine Fuels

| Code | Description |
|------|-------------|
| VLSFO_USD | Very Low Sulphur Fuel Oil (0.5% S) |
| MGO_05S_USD | Marine Gasoil (0.5% S) |
| HFO_180_USD | Heavy Fuel Oil 180 CST |
| HFO_380_USD | Heavy Fuel Oil 380 CST |

### Coal

| Code | Description |
|------|-------------|
| COAL_USD | Thermal coal benchmark |
| NEWCASTLE_COAL_USD | Newcastle thermal coal (Asia benchmark) |
| CME_COAL_USD | CME Coal futures |
| COKING_COAL_USD | Metallurgical / coking coal |
| CAPP_COAL_USD | Central Appalachian coal (spot) |
| CAPP_COAL_ANNUAL_USD | Central Appalachian coal (annual) |
| ILLINOIS_COAL_USD | Illinois Basin coal (spot) |
| ILLINOIS_COAL_ANNUAL_USD | Illinois Basin coal (annual) |
| PRB_COAL_USD | Powder River Basin coal (spot) |
| PRB_COAL_ANNUAL_USD | Powder River Basin coal (annual) |
| NYMEX_APPALACHIAN_USD | NYMEX Appalachian coal |
| NYMEX_WESTERN_RAIL_USD | NYMEX Western rail coal |

### Carbon Allowances

| Code | Description |
|------|-------------|
| EU_CARBON_EUR | EU ETS carbon permits (EUR/tCO2) |
| EU_CARBON_FUTURES | EU carbon futures |
| UK_CARBON_GBP | UK ETS carbon permits (GBP/tCO2) |

### Precious Metals

| Code | Description |
|------|-------------|
| GOLD_USD | Spot gold (USD/oz) |
| SILVER_USD | Spot silver (USD/oz) |
| URANIUM_USD | Uranium (USD/lb) |
| GOLD_AM_USD | LBMA Gold AM Fix (USD) |
| GOLD_AM_GBP | LBMA Gold AM Fix (GBP) |
| GOLD_AM_EUR | LBMA Gold AM Fix (EUR) |
| GOLD_PM_USD | LBMA Gold PM Fix (USD) |
| GOLD_PM_GBP | LBMA Gold PM Fix (GBP) |
| GOLD_PM_EUR | LBMA Gold PM Fix (EUR) |
| SILVER_FIX_USD | LBMA Silver Fix (USD) |
| SILVER_FIX_GBP | LBMA Silver Fix (GBP) |
| SILVER_FIX_EUR | LBMA Silver Fix (EUR) |

### Forex Pairs

| Code | Description |
|------|-------------|
| EUR_USD | Euro / US Dollar |
| GBP_USD | British Pound / US Dollar |
| USD_NOK | US Dollar / Norwegian Krone |
| EUR_NOK | Euro / Norwegian Krone |

### Futures Contracts (higher tiers / add-on)

| Code | Description |
|------|-------------|
| BRENT_FUTURES | ICE Brent futures curve |
| BRENT_FUTURES_CONTINUOUS | Brent continuous front-month |
| WTI_FUTURES | NYMEX WTI futures curve |
| WTI_FUTURES_CONTINUOUS | WTI continuous front-month |
| GASOIL_FUTURES | ICE Gasoil futures |
| NATGAS_FUTURES | Henry Hub natural gas futures |
| TTF_FUTURES | ICE TTF gas futures |
| EUA_CARBON_FUTURES | ICE EUA carbon futures |
| JKM_FUTURES | JKM LNG 12-contract delayed/reference curve; coverage_status full_curve_reference and source_semantics delayed_reference_non_official; not official CME settlement data |

### Natural Gas Storage

| Code | Description |
|------|-------------|
| NATURAL_GAS_STORAGE | EIA weekly storage report (Bcf) |
| NATURAL_GAS_STORAGE_LEGACY | Legacy storage data |
| CUSHING_STORAGE | Cushing OK crude storage (barrels) |

### Drilling Intelligence (higher tiers / add-on)

| Code | Description |
|------|-------------|
| US_RIG_COUNT | Baker Hughes US active rig count |
| CANADA_RIG_COUNT | Baker Hughes Canada rig count |
| INTERNATIONAL_RIG_COUNT | Baker Hughes international rig count |
| US_FRAC_SPREAD_COUNT | US frac spread count |

#### Basin-Level Drilling Data

Available for basins: PERMIAN, BAKKEN, EAGLEFORD, ANADARKO, APPALACHIA, HAYNESVILLE, NIOBRARA

Pattern: `{BASIN}_WELLS_DRILLED`, `{BASIN}_WELLS_COMPLETED`, `{BASIN}_DUC_WELLS`

Frac spreads available for: PERMIAN, BAKKEN, EAGLEFORD
Pattern: `{BASIN}_FRAC_SPREADS`

Well permits: `TEXAS_WELL_PERMITS`, `OKLAHOMA_WELL_PERMITS`, `NORTH_DAKOTA_WELL_PERMITS`

---

## Rate Limiting

Every API response includes rate limit headers:

| Header | Description |
|--------|-------------|
| X-RateLimit-Limit | Max requests allowed per month |
| X-RateLimit-Remaining | Requests remaining this month |
| X-RateLimit-Reset | Unix timestamp when limit resets |

When you exceed your limit, the API returns HTTP 429 Too Many Requests.

---

## Error Codes

| HTTP Status | Meaning | Common Cause |
|-------------|---------|--------------|
| 200 | Success | Request completed |
| 400 | Bad Request | Invalid commodity code or malformed request |
| 401 | Unauthorized | Missing or invalid API key |
| 403 | Forbidden | Plan does not include requested data |
| 404 | Not Found | Endpoint does not exist |
| 429 | Too Many Requests | Monthly request limit exceeded |
| 500 | Internal Server Error | Server-side issue (retry with backoff) |

Error response format:

```json
{
  "status": "error",
  "message": "Invalid commodity code: INVALID_CODE"
}
```

---

## Pricing Plans

| Plan | Price | Requests/Month | Key Features |
|------|-------|----------------|--------------|
| Free | $0/mo | 200 | All spot prices, 1 API key |
| Developer | $19/mo | 10,000 | Entry paid tier; current inclusions are listed on pricing |
| Starter | $49/mo | 50,000 | + Historical data, webhook alerts |
| Professional | $99/mo | 100,000 | + Higher limits, priority support |
| Scale | $299/mo | 1,000,000 | + Highest limits, production workflows |

Futures curves and Drilling Intelligence are available on higher tiers or as add-ons; see https://www.oilpriceapi.com/pricing for current plans and feature gates.

Signup: https://www.oilpriceapi.com/auth/signup
Pricing details: https://www.oilpriceapi.com/pricing

---

## SDKs and Integrations

| Platform | Install Command | Link |
|----------|----------------|------|
| Python | `pip install oilpriceapi` | [Docs](https://docs.oilpriceapi.com/developers/python) |
| JavaScript/Node.js | `npm install oilpriceapi` | [Docs](https://docs.oilpriceapi.com/developers/javascript) |
| Go | `go get github.com/OilpriceAPI/oilpriceapi-go` | [Docs](https://docs.oilpriceapi.com/developers/go) |
| Ruby | `gem install oilpriceapi` | [Docs](https://docs.oilpriceapi.com/developers/ruby) |
| C# | NuGet: OilPriceAPI | [Docs](https://docs.oilpriceapi.com/developers/csharp) |
| MCP Server | `npm install oilpriceapi-mcp` | [npm](https://www.npmjs.com/package/oilpriceapi-mcp) |
| Google Sheets | Add-on | [Docs](https://docs.oilpriceapi.com/integrations/google-sheets) |
| Power BI | Connector | [Docs](https://docs.oilpriceapi.com/integrations/power-bi) |
| Zapier | Integration | [Docs](https://docs.oilpriceapi.com/integrations/zapier) |
| n8n | Integration | [Docs](https://docs.oilpriceapi.com/integrations/n8n) |

OpenAPI Spec (Swagger): https://api.oilpriceapi.com/api-docs

---

## Agent Best Practices

1. **Use the batch endpoint** — `POST /v1/prices/batch` fetches multiple commodities in one request, saving your rate limit.

2. **Start with the demo endpoint** — `GET /v1/demo/prices` requires no authentication and is ideal for testing your integration.

3. **Cache responses** — Use the returned source timestamp and a cache policy appropriate to the selected source and dataset; there is no single sitewide refresh cadence.

4. **Check rate limit headers** — Read `X-RateLimit-Remaining` from every response. Stop making requests when remaining is low.

5. **Use commodity codes exactly** — Codes are case-sensitive and use UPPER_SNAKE_CASE (e.g., `BRENT_CRUDE_USD`, not `brent_crude_usd`).

6. **Handle 429 gracefully** — If you hit the rate limit, wait until the `X-RateLimit-Reset` timestamp before retrying.

7. **Use the MCP server for Claude/Cursor** — The `oilpriceapi-mcp` package provides native tool integration for AI coding environments.

8. **Prefer specific codes over /v1/prices/all** — The batch endpoint with specific codes is faster and uses fewer resources than fetching all prices.

---

## Quick Start for AI Agents

Minimal working example to get Brent crude price:

```bash
curl -H "Authorization: Token YOUR_API_KEY" \
  "https://api.oilpriceapi.com/v1/prices/latest?by_code=BRENT_CRUDE_USD"
```

Or without auth (demo):

```bash
curl https://api.oilpriceapi.com/v1/demo/prices
```

Python:

```python
import requests

headers = {"Authorization": "Token YOUR_API_KEY"}
response = requests.get(
    "https://api.oilpriceapi.com/v1/prices/latest",
    params={"by_code": "BRENT_CRUDE_USD"},
    headers=headers
)
data = response.json()
price = data["data"]["price"]
```

JavaScript:

```javascript
const response = await fetch(
  "https://api.oilpriceapi.com/v1/prices/latest?by_code=BRENT_CRUDE_USD",
  { headers: { "Authorization": "Token YOUR_API_KEY" } }
);
const { data } = await response.json();
const price = data.price;
```