---
title: "Convert between metals, currencies, and units"
method: GET
path: "/v1/convert"
tags: ["convert"]
---

# Convert between metals, currencies, and units

`GET /v1/convert`

Convert an amount between metals, currencies, and units.

- metal → currency: spot price in that currency via FX cross through USD
- currency → metal: inverse of the above
- metal → metal: ratio of USD spot prices
- currency → currency: FX cross through USD (live raw_exchangerate_fx
  first, raw_frankfurter daily-ECB fallback)

Two-leg source skew: currency → currency conversions resolve EACH leg
independently through the live-first/daily-fallback chain, so the two
legs can come from different sources and ages (e.g. a live EUR rate
crossed with a daily-ECB THB rate). The response `timestamp` reflects
the `to` leg only — the `from` leg's timestamp is discarded — so it
can understate (or overstate) the age of the other half of the cross.
Both legs share the USD anchor, so cross drift is bounded by the
staleness of the older leg — never compounded.

The `unit` param applies to the metal side only (oz / gram / kg).
Historical conversion via `date` is not supported; use /v1/bars +
/v1/prices/history for historical spot data.

## Query parameters

- `from` string, required — Source symbol: XAU, XAG, USD, EUR, …
- `to` string, required — Target symbol: USD, EUR, XAU, …
- `amount` number — Amount to convert (default 1).
- `unit` string — Unit for the metal side: oz | gram | kg (default oz).

## Response `200`

Successful Response

- ConvertResponse — Response for GET /v1/convert.
  - `from` string, required — Source symbol (e.g. XAU, USD).
  - `to` string, required — Target symbol (e.g. USD, EUR).
  - `amount` string, required — Input amount.
  - `rate` string, required — Conversion rate (1 from-unit = rate to-units).
  - `result` string, required — amount x rate.
  - `unit` string, required — Unit applied to the metal side (oz, gram, kg).
  - `timestamp` string, required — UTC ISO-8601 timestamp of the source data. For currency-to-currency conversions the two FX legs resolve independently (live-first with daily fallback) and may differ in source/age; this reflects one leg only.

## Other responses

- `400` — Bad Request
- `401` — Unauthorized
- `403` — Forbidden
- `404` — Not Found
- `422` — Validation Error
- `429` — Too Many Requests
- `503` — Service Unavailable

---

[API](https://skmtc.net/goldprice/apis/gold-api.md) · [All operations](https://skmtc.net/goldprice/apis/gold-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/goldprice/gold-api/versions/7885a141754c/schema)