`GET /v1/convert`

Converts an exact decimal amount between two assets using the current stored rate. The multiplication is performed in exact decimal arithmetic — no binary floating point is involved at any point.

Need this over MCP instead? See convert_currency →.

Auth

Authorization: ApiKey <key> — required.

Query parameters

Parameter	Required	Rules
`from`	yes	Trimmed, uppercased, must match `^[A-Z0-9]{2,10}$`
`to`	yes	Same rules as `from`
`amount`	yes	Exact decimal string, non-negative, up to 30 significant digits

amount is a string. Sending it as a JSON number elsewhere in your stack is the usual way precision gets lost before the request is even made.

Malformed input is rejected before any charge is made:

Status	Code
`400`	`invalid_asset_symbol`
`400`	`invalid_amount`

Billing

One request unit, charged once, after validation and before the rate is read. A conversion costs the same as a rate read.

Success — `200`


curl "https://your-getratesapi-host/v1/convert?from=BTC&to=CZK&amount=0.25" \
  -H "Authorization: ApiKey gra_live_0000000000000000000000000000000000000000000000000000000000000000"


const params = new URLSearchParams({ from: "BTC", to: "CZK", amount: "0.25" });
const res = await fetch(`https://your-getratesapi-host/v1/convert?${params}`, {
  headers: {
    Authorization: "ApiKey gra_live_0000000000000000000000000000000000000000000000000000000000000000",
  },
});
const conversion = await res.json();


{
  "from": "BTC",
  "to": "CZK",
  "amount": "0.25",
  "rate": "1543210.98765",
  "converted_amount": "385802.7469125",
  "as_of": "2026-09-29T11:41:32.241582Z",
  "status": "fresh",
  "type": "derived"
}

rate and converted_amount are exact decimal strings, never JSON numbers. converted_amount is not rounded to the target currency’s minor unit — rounding is a presentation decision and belongs to your application, which knows whether it is displaying, invoicing, or settling.
type is direct or derived; see derived rates.
status is fresh or stale; see freshness.
as_of is the observation time of the underlying rate. For a derived rate it is the oldest contributing observation.

Converting an asset to itself returns the input amount with rate of 1.

Other error outcomes

These happen after a successful charge — the unit is consumed, with no refund:

Status	Code
`404`	`unsupported_pair`
`503`	`temporarily_unavailable`

GET /v1/convert