# 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. Covers 100+ energy commodity codes across crude oil, natural gas, refined products, coal, LNG, marine fuels, carbon allowances, precious metals, forex, drilling intelligence, and futures.

---

## Authentication

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

```
Authorization: Token YOUR_API_KEY
```

Get a free API key (200 requests/month, no credit card): 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 (Reservoir Mastery+ plans)

| 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 |

### 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 (Reservoir Mastery+ plans)

| 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 |
| Exploration | $15/mo | 10,000 | All spot prices, 5 API keys |
| Production | $45/mo | 50,000 | + Historical data, webhook alerts |
| Reservoir Mastery | $129/mo | 250,000 | + Futures curves, drilling intelligence, basin data |
| Enterprise | Custom | Custom | Dedicated support, SLA, custom feeds |

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** — Prices update every 1-2 minutes. Cache results for at least 60 seconds to avoid unnecessary requests.

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;
```