How to Get the Gold Jun 2026 (GCM26) - Per Troy Ounce Price via a REST API endpoint

Metals-API 9 min read
How to Get the Gold Jun 2026 (GCM26) - Per Troy Ounce Price via a REST API endpoint

You need the per–troy ounce price of the Gold June 2026 futures contract (GCM26) to value positions, quote a price in your app, or backfill a chart. By the end of this guide you will know how to query a REST endpoint to retrieve GCM26 pricing in USD per troy ounce, invert it correctly when needed, convert amounts with the convert endpoint, and handle contract expiry and caching in production.

What you’ll fetch and how the units work

GCM26 is a month-coded gold futures symbol (June 2026). Metals-API returns metals and contract symbols relative to a base currency, which by default is USD. That means:

Illustration: How to Get the Gold Jun 2026 (GCM26) - Per Troy Ounce Price via a REST API endpoint
  • rates.GCM26 = troy ounces per 1 USD (oz/USD)
  • rates.USDGCM26 = USD per 1 troy ounce (USD/oz), i.e., the more directly useful “price per ounce”

If you only request GCM26 you will receive oz per USD, which you can invert to get USD per oz. To save a step, request USDGCM26 alongside GCM26 in the same call.

Units are troy ounces by default. If you need grams, multiply USD/oz by 1/31.1034768, or convert ounces by 31.1034768 to grams. Keep this distinction in mind when integrating into jewelry, manufacturing, or research pipelines.

Quick start: fetch USD per troy ounce for GCM26

This call asks for the latest rates for both GCM26 (oz/USD) and USDGCM26 (USD/oz) so you can choose the one you prefer in downstream code.

curl "https://metals-api.com/api/latest?access_key=YOUR_API_KEY&symbols=GCM26,USDGCM26"

Example of a real JSON response for GCM26 from the latest endpoint:

{"success":true,"timestamp":1792627680,"date":"2026-10-22","base":"USD","rates":{"GCM26":0.00021843599825251,"USD":1,"USDGCM26":4578.000000000042},"warnings":[{"symbol":"GCM26","code":410,"type":"expired_symbol","info":"The requested symbol has expired and is no longer available."}]}

What you’ll actually use from this payload

  • rates.USDGCM26: USD per 1 troy ounce of the GCM26 contract. This is the direct per-ounce price to display, store, or feed into calculations.
  • rates.GCM26: troy ounces per 1 USD. If USDGCM26 is absent, compute price_per_oz = 1 / rates.GCM26.
  • timestamp and date: The Unix timestamp (seconds) and UTC date of the quote. Use these for caching and charting.
  • warnings: Here, code 410 indicates the symbol is expired and no longer updating. Use this to switch to an active contract or to backfill historical data.

For parameter and field details, see the Metals-API Documentation. To check how GCM26 and related symbols are named, look them up in the Metals-API Supported Symbols.

Python example: read USD/oz, invert if needed, and surface expiry

import os
import requests
from decimal import Decimal, InvalidOperation

API_KEY = os.getenv("METALS_API_KEY", "YOUR_API_KEY")
URL = "https://metals-api.com/api/latest"

params = {
"access_key": API_KEY,
# Ask for both, so we can prefer USD/oz directly and fall back to inversion
"symbols": "GCM26,USDGCM26"
}

resp = requests.get(URL, params=params, timeout=10)
resp.raise_for_status()
data = resp.json()

if not data.get("success", False):
raise RuntimeError(f"API error: {data}")

rates = data.get("rates", {})
warnings = data.get("warnings", [])
timestamp = data.get("timestamp")
as_of_date = data.get("date")

# Prefer direct USD per ounce if present
price_usd_per_oz = rates.get("USDGCM26")

if price_usd_per_oz is None:
# Fallback: invert oz/USD
gcm26_oz_per_usd = rates.get("GCM26")
if gcm26_oz_per_usd in (None, 0):
raise ValueError("No usable rate found for GCM26 or USDGCM26")
try:
price_usd_per_oz = float(Decimal(1) / Decimal(str(gcm26_oz_per_usd)))
except (InvalidOperation, ZeroDivisionError) as e:
raise ValueError(f"Failed to invert GCM26 rate: {e}")
else:
# Normalize to float if it's a string/decimal
price_usd_per_oz = float(price_usd_per_oz)

print(f"As of {as_of_date} (ts={timestamp}), GCM26 price = {price_usd_per_oz:.6f} USD/oz troy")

# Optional: handle expiry warning code 410
expired = any(w.get("symbol") == "GCM26" and str(w.get("code")) == "410" for w in warnings)
if expired:
print("Note: GCM26 is expired; switch to an active contract for live pricing or use historical endpoints for backfill.")

Tips for production:

  • Cache by timestamp/date. If the timestamp hasn’t advanced since your last call, serve the cached value.
  • Treat warning code 410 as a signal to roll to an active month (for example, front-month gold) based on your trading logic. Use the Supported Symbols list to identify the right code.
  • All dates in responses are UTC. The timestamp is Unix seconds; convert to your users’ timezone in your UI, not in storage.

Convert endpoint: translate budgets and weights to contract ounces

You often need to answer questions like “how many ounces of GCM26 can I buy with $100,000?” or “what’s the USD value of 250 troy ounces at the GCM26 price?” Use the convert endpoint for this, specifying from, to, and amount.

Example: convert USD to GCM26 ounces

curl "https://metals-api.com/api/convert?access_key=YOUR_API_KEY&from=USD&to=GCM26&amount=100000"

Notes for integration:

  • from and to can be USD and the contract symbol (GCM26) in either direction.
  • The conversion is based on the latest available rate at the time of the call. Store the returned timestamp if present to keep a clear valuation audit trail.
  • If you need grams instead of troy ounces, convert the returned ounces with the factor 31.1034768 g/oz.

See parameter options and usage patterns in the Documentation. If you’re new to the API, you can get an API key here: Register.

Handling symbol expiry, rollovers, and market hours

The real response above includes warnings: code 410 expired_symbol for GCM26. That means:

  • Expired contracts no longer update on the latest endpoint.
  • Use that warning to switch to an active month for live pricing, according to your roll convention (e.g., volume/open interest, or a fixed day offset).
  • If you are doing historical analysis or backfills for GCM26, use historical or time-series endpoints by date. For date limits and parameters, refer to the Documentation.

Non-trading days and weekends: latest values may hold steady across weekends or holidays. Guard your alerting and intraday logic so it does not fire on a stale timestamp; check the timestamp field and pause alerts when the feed’s timestamp hasn’t advanced.

Best practices for accurate USD/oz pricing

  • Always request USDGCM26 alongside GCM26. Prefer USDGCM26 (USD per troy ounce) for pricing; invert GCM26 (oz/USD) only if USDGCM26 is unavailable.
  • Normalize precision. Treat prices as Decimal in financial code paths to avoid floating-point rounding issues during conversions and P&L aggregation.
  • Cache responses keyed by symbol and timestamp. If your application polls faster than the feed updates, serve the cached value and skip a downstream re-valuation to reduce noise.
  • Validate units at integration boundaries. Store a “unit” flag with each value (e.g., USD/oz_t). If you convert to grams or kilograms, store both the numeric value and the unit you’ve derived.
  • Surface warnings to operators. If a response contains an expired_symbol warning, log it and trigger a roll procedure. This avoids silent stale pricing on retired contracts.

Tying it into trading and analytics workflows

Developers in trading tools, digital gold platforms, and ERP pricing modules can integrate this endpoint to:

  • Display a per-ounce USD price for GCM26 in a quote panel or product page.
  • Convert budgets or inventory weights via the convert endpoint and record the valuation timestamp.
  • Backfill historical valuations for GCM26 by date, then roll to the next contract month when you encounter an expired_symbol warning.

For deeper capabilities (e.g., time series or OHLC by date), review the endpoint catalog and parameters in the Documentation, and confirm instrument availability in the Symbols list.

Operational notes: auth, reliability, and integration hygiene

  • Authentication: pass your API key via the access_key query parameter as shown in the curl examples.
  • Timeouts and retries: set reasonable client timeouts and idempotent retries for GET requests. Avoid retry storms; back off if the timestamp hasn’t changed.
  • Change detection: build dashboards to highlight when price.timestamp changes, not just when price value changes, to catch late-session updates or minor revisions.
  • Auditing: store the raw JSON blob or the subset of fields you used (symbol, base, USDGCM26 or GCM26, timestamp, date) for reproducibility in reports.

Why accurate gold per-ounce data matters in digital workflows

Gold price discovery now drives a wide set of digital experiences: automated hedging in fintech apps, dynamic pricing for jewelry e-commerce in different currencies, ERP cost updates for manufacturers, and research dashboards that model roll yields across futures months. Metals-API’s JSON endpoints let you stitch these flows into your own stack with minimal glue code: fetch USD per troy ounce, convert amounts, and monitor contract rollovers programmatically.

To explore managed connectivity and platform options, see MCP. To get started with your own API key, go to Register. You can always return to the main site at metals-api.com for product overviews and updates.

Troubleshooting and edge cases

  • If USDGCM26 is missing, invert GCM26. Keep a guard against division by zero and treat nulls as unavailable.
  • If you receive expired_symbol for GCM26, switch to an active contract month for live pricing and use historical endpoints to backfill the expired month by date.
  • If rates lag over weekends or holidays, rely on the timestamp to decide whether to refresh UI components or keep cached values.
  • If you need another currency (e.g., EUR per ounce), retrieve USD/oz and convert in your app using your FX source, or consult the Documentation for currency options.

FAQ

Q: Is GCM26 a spot gold price or a futures contract?
A: GCM26 is a June 2026 gold futures contract code. For spot metal symbols, review the list in Symbols.

Q: Why does the response include an expired_symbol warning for GCM26?
A: It indicates the requested contract has passed its active period and no longer updates on the latest endpoint. Use the warning to roll to an active month for live pricing and rely on historical endpoints for backfills by date.

Q: What’s the difference between GCM26 and USDGCM26 in the rates object?
A: GCM26 is quoted as troy ounces per USD (oz/USD). USDGCM26 is the inversion—USD per troy ounce (USD/oz). For display and valuation, USDGCM26 is usually what you want.

Q: What timezone are dates in, and what does timestamp represent?
A: date is in UTC. timestamp is a Unix epoch in seconds. Use it for caching, deduping updates, and labeling chart points accurately.

Q: Can I convert a dollar budget directly into GCM26 ounces?
A: Yes. Use the convert endpoint with from=USD, to=GCM26, and your amount. See the curl example above.

Ship your integration: get an API key in minutes and start pulling per–troy ounce prices for gold contracts like GCM26. Create your account here: Register. Explore endpoint details and options in the Documentation, and browse instruments in Symbols.