---
title: "GET /metals/spot"
method: GET
path: "/metals/spot"
tags: ["metals", "plan-premium"]
---

# GET /metals/spot

`GET /metals/spot`

Spot price for a single metal, in the currency, unit of mass and purity you ask for.

The instrument actually quoted is chosen from the metal, currency and unit together, and is reported as `source_instrument`. Where no instrument is quoted directly in the requested currency, the price is crossed via USD and `cross_rate` is true - this consumes an additional FX product call and widens the bid/ask gap.

## Query parameters

- `metal` string — Three-letter metal symbol, e.g. XAU for gold
- `currency` string — Three-letter ISO 4217 currency code
- `unit` 'gram' | 'kilogram' | 'metric_tonne' | 'grain' | 'pennyweight' | 'oz_t' | 'lb_t' | 'oz_av' | 'lb_av' | 'tael' | 'baht' | 'tola' — Handle for a unit of mass that metal prices can be quoted in
- `purity` string — A purity code from /metals/purities (e.g. '750'), or any custom fineness in parts per thousand between 1 and 1000. A custom value is echoed back with a purity_name of 'custom'.
- `verbose` string — Truthy values are true, 1, yes and y. Anything else is treated as false.

## Response `200`

Success

- object — A spot price converted to the requested currency, unit and purity. The *_name fields appear only when verbose is set. grade fields appear for base metals, purity fields for precious metals.
  - `bid` string, required — A price, as a string to preserve the significant figures of the source quote. Parse as a decimal rather than a float where precision matters.
  - `ask` string — A price, as a string to preserve the significant figures of the source quote. Parse as a decimal rather than a float where precision matters.
  - `mid` string — A price, as a string to preserve the significant figures of the source quote. Parse as a decimal rather than a float where precision matters.
  - `spread` string — A price, as a string to preserve the significant figures of the source quote. Parse as a decimal rather than a float where precision matters.
  - `metal` string, required — Three-letter metal symbol, e.g. XAU for gold
  - `metal_name` string — Metal name. Verbose only.
  - `currency` string, required — Three-letter ISO 4217 currency code
  - `currency_name` string — Currency name. Verbose only.
  - `unit` 'gram' | 'kilogram' | 'metric_tonne' | 'grain' | 'pennyweight' | 'oz_t' | 'lb_t' | 'oz_av' | 'lb_av' | 'tael' | 'baht' | 'tola', required — Handle for a unit of mass that metal prices can be quoted in
  - `unit_name` string — Display name for the unit. Verbose only.
  - `tsp` number, required — Milliseconds since Jan 1 1970 (unix timestamp with millisecond precision)
  - `dtm` string, required — Quote time, formatted per the account's datetime format
  - `cross_rate` boolean, required — True when the price was crossed via USD rather than quoted directly in the requested currency
  - `source` string, required — Origin of the price data
  - `source_instrument` string, required — The instrument actually quoted to build this price
  - `grade` string — Deliverable contract grade. Base metals only.
  - `grade_name` string — Display name for the contract grade. Base metals only, verbose only.
  - `grade_min_purity_pct` number, float — Minimum purity of the contract grade, as a percentage. Base metals only, verbose only.
  - `purity` string — Purity code the price is quoted at. Precious metals only.
  - `purity_name` string — Display name for the purity, or 'custom' for a caller-supplied fineness. Precious metals only.
  - `ms` number — Server response time in milliseconds

## Other responses

- `400` — Bad Request - unknown metal, currency, unit or purity
- `401` — Not Authorized
- `403` — Forbidden
- `429` — Rate limit exceeded
- `500` — Upstream price data unavailable

---

[API](https://skmtc.dev/fastforex/apis/fastforex-io.md) · [All operations](https://skmtc.dev/fastforex/apis/fastforex-io/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/fastforex/fastforex-io/revisions/140f748aaf10/schema)