> ## Documentation Index
> Fetch the complete documentation index at: https://finance.chiefpriest.design/llms.txt
> Use this file to discover all available pages before exploring further.

# Commodities Prices

> Get current prices for commodities including energy, metals, and agriculture

Get real-time and historical prices for major commodities across energy, metals, and agricultural sectors.

## Parameters

<ParamField query="commodity_type" type="string" default="all">
  Type of commodities to retrieve:

  * `all`: All commodities
  * `energy`: Oil, gas, coal
  * `metals`: Gold, silver, copper, etc.
  * `agriculture`: Wheat, corn, soybeans, etc.
</ParamField>

## Response

<ResponseField name="commodities" type="array">
  Array of commodity price data

  <Expandable title="Commodity object properties">
    <ResponseField name="symbol" type="string">
      Commodity symbol/code
    </ResponseField>

    <ResponseField name="name" type="string">
      Commodity name
    </ResponseField>

    <ResponseField name="price" type="number">
      Current price
    </ResponseField>

    <ResponseField name="change" type="number">
      Price change in absolute terms
    </ResponseField>

    <ResponseField name="changesPercentage" type="number">
      Price change as percentage
    </ResponseField>

    <ResponseField name="unit" type="string">
      Price unit (per barrel, per ounce, etc.)
    </ResponseField>

    <ResponseField name="category" type="string">
      Commodity category (energy, metals, agriculture)
    </ResponseField>

    <ResponseField name="lastUpdated" type="string">
      When the price was last updated
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="timestamp" type="string">
  When the data was retrieved
</ResponseField>

<RequestExample>
  ```bash cURL theme={null}
  curl -X GET "https://stocks-dev.up.railway.app/api/v1/commodities?commodity_type=energy" \
    -H "X-API-Key: your_api_key"
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch('/api/v1/commodities?commodity_type=energy', {
    headers: {
      'X-API-Key': 'your_api_key'
    }
  });
  const data = await response.json();
  ```

  ```python Python theme={null}
  import requests

  response = requests.get(
      'https://stocks-dev.up.railway.app/api/v1/commodities',
      params={'commodity_type': 'energy'},
      headers={'X-API-Key': 'your_api_key'}
  )
  data = response.json()
  ```
</RequestExample>

<ResponseExample>
  ```json Response theme={null}
  {
    "commodities": [
      {
        "symbol": "CL=F",
        "name": "Crude Oil WTI",
        "price": 78.45,
        "change": 1.23,
        "changesPercentage": 1.59,
        "unit": "per barrel",
        "category": "energy",
        "lastUpdated": "2024-01-19T15:30:00Z"
      },
      {
        "symbol": "BZ=F",
        "name": "Brent Crude Oil",
        "price": 82.67,
        "change": 0.89,
        "changesPercentage": 1.09,
        "unit": "per barrel",
        "category": "energy",
        "lastUpdated": "2024-01-19T15:30:00Z"
      },
      {
        "symbol": "NG=F",
        "name": "Natural Gas",
        "price": 2.845,
        "change": -0.125,
        "changesPercentage": -4.21,
        "unit": "per MMBtu",
        "category": "energy",
        "lastUpdated": "2024-01-19T15:30:00Z"
      }
    ],
    "timestamp": "2024-01-19T15:30:00Z"
  }
  ```
</ResponseExample>

## Commodity Categories

### Energy

* **Crude Oil WTI**: West Texas Intermediate crude oil
* **Brent Crude**: International crude oil benchmark
* **Natural Gas**: Natural gas futures
* **Heating Oil**: Heating oil futures
* **Gasoline**: Gasoline futures

### Metals

* **Gold**: Gold spot price
* **Silver**: Silver spot price
* **Copper**: Copper futures
* **Platinum**: Platinum spot price
* **Palladium**: Palladium spot price

### Agriculture

* **Wheat**: Wheat futures
* **Corn**: Corn futures
* **Soybeans**: Soybean futures
* **Sugar**: Sugar futures
* **Coffee**: Coffee futures
* **Cotton**: Cotton futures

## Use Cases

* **Portfolio Diversification**: Add commodity exposure
* **Inflation Hedging**: Track inflation-sensitive assets
* **Economic Analysis**: Monitor economic indicators
* **Trading Opportunities**: Identify commodity trends
* **Risk Management**: Hedge commodity price exposure

## Price Units

Different commodities are quoted in different units:

* **Oil**: Per barrel (42 gallons)
* **Natural Gas**: Per MMBtu (million British thermal units)
* **Gold/Silver**: Per troy ounce
* **Agricultural**: Per bushel or per pound

## Data Source

This endpoint uses Financial Modeling Prep (FMP) commodity data with real-time pricing from major exchanges.

## Notes

* Prices are updated throughout trading hours
* Some commodities trade 24/7, others have specific hours
* Prices may include storage, transportation, and delivery costs
* Consider seasonal patterns for agricultural commodities
* Energy prices are highly volatile and news-sensitive