API docs

Overview

Lume Exchange Rates brings exchange-rate comparison, conversion and historical charts into one place. Choose the currencies that matter to you, whether you are planning a trip, comparing an international price or building a product.

We use External exchange-rate provider as the configured source. Each latest-rate response identifies its source and publication time. Available currency symbols are updated from the latest provider data.

Quick start

Production external JSON APIs are currently disabled. Examples below require an enabled environment and a valid paid API key. Browser login alone does not authorize API calls. The website calculator remains available.

export LUME_API_URL='https://lumeexchangerates.com'
export LUME_API_KEY='YOUR_API_KEY'
curl --fail-with-body -H "Authorization: Bearer $LUME_API_KEY" "$LUME_API_URL/v1/quotes?anchor=USD&targets=EUR,JPY"

const response = await fetch(process.env.LUME_API_URL + '/v1/quotes?anchor=USD&targets=EUR,JPY', {
  headers: { Authorization: 'Bearer ' + process.env.LUME_API_KEY }
});
const body = await response.json();
if (!response.ok) throw new Error(body.error?.code || 'HTTP_' + response.status);
console.log(body.anchor, body.meta.timestamp, body.data);

Access & authentication

Manage customer keys in /account. Key issuance and rate access require an active paid subscription and server-confirmed payment. Unsubscribed accounts have no free API allowance. Provider credentials remain server-side.

Authorization: Bearer lume_…

Keep secret keys on servers. Configured IP/domain restrictions must all match. CORS is opt-in for explicitly allowed HTTPS origins and never replaces authentication.

Endpoints

GET /v1/currencies

All symbols with current rates, with provider names. Includes available alternatives and metals.

Parameter: —

curl --request GET 'https://staging.lumeexchangerates.com/v1/currencies' --header 'Authorization: Bearer YOUR_API_KEY'

The values and dates below illustrate response structure; they are not live rates. Arrays may show only a subset. Use the API explorer for current data.

{
  "meta": {
    "mode": "provider",
    "source": "External exchange-rate provider",
    "source_url": "https://openexchangerates.org/",
    "as_of": "2026-01-01T00:00:00.000Z",
    "fetched_at": "2026-01-01T00:00:05.000Z",
    "currency_count": 3,
    "includes_alternative": true,
    "refresh_interval_seconds": 300,
    "provider_plan": "Unlimited",
    "notice": "Illustrative response; not live rates."
  },
  "data": [
    {
      "code": "USD",
      "name": "United States Dollar"
    },
    {
      "code": "EUR",
      "name": "Euro"
    },
    {
      "code": "JPY",
      "name": "Japanese Yen"
    }
  ]
}

GET /v1/quotes

Base symbol; defaults to USD. Any current provider symbol is accepted.

curl --request GET 'https://staging.lumeexchangerates.com/v1/quotes?anchor=USD&targets=EUR,JPY' --header 'Authorization: Bearer YOUR_API_KEY'

The values and dates below illustrate response structure; they are not live rates. Arrays may show only a subset. Use the API explorer for current data.

{
  "meta": {
    "mode": "provider",
    "source": "External exchange-rate provider",
    "source_url": "https://openexchangerates.org/",
    "as_of": "2026-01-01T00:00:00.000Z",
    "fetched_at": "2026-01-01T00:00:05.000Z",
    "currency_count": 3,
    "includes_alternative": true,
    "refresh_interval_seconds": 300,
    "provider_plan": "Unlimited",
    "notice": "Illustrative response; not live rates."
  },
  "anchor": "USD",
  "data": [
    {
      "currency": "EUR",
      "value": 0.9
    },
    {
      "currency": "JPY",
      "value": 150
    }
  ]
}

Example: /v1/quotes?anchor=EUR&targets=USD,JPY. value is target units per one anchor unit. Duplicate targets are removed. Empty, lowercase or unavailable symbols return 400.

GET /v1/exchange

Non-negative numeric amount to convert.

curl --request GET 'https://staging.lumeexchangerates.com/v1/exchange?from=USD&to=EUR&quantity=100' --header 'Authorization: Bearer YOUR_API_KEY'

The values and dates below illustrate response structure; they are not live rates. Arrays may show only a subset. Use the API explorer for current data.

{
  "meta": {
    "mode": "provider",
    "source": "External exchange-rate provider",
    "source_url": "https://openexchangerates.org/",
    "as_of": "2026-01-01T00:00:00.000Z",
    "fetched_at": "2026-01-01T00:00:05.000Z",
    "currency_count": 3,
    "includes_alternative": true,
    "refresh_interval_seconds": 300,
    "provider_plan": "Unlimited",
    "notice": "Illustrative response; not live rates."
  },
  "data": {
    "from": "USD",
    "to": "EUR",
    "quantity": 100,
    "rate": 0.9,
    "result": 90
  }
}

Example: /v1/exchange?from=USD&to=EUR&quantity=100. Always specify from and to in global integrations. This legacy GET route defaults to EUR. Empty values, negatives, NaN, infinity and result overflow return 400.

GET /api/rates/latest

Latest published rate

Parameter: —

curl --request GET 'https://staging.lumeexchangerates.com/api/rates/latest' --header 'Authorization: Bearer YOUR_API_KEY'

The values and dates below illustrate response structure; they are not live rates. Arrays may show only a subset. Use the API explorer for current data.

{
  "meta": {
    "provider": "External exchange-rate provider",
    "kind": "latest_published",
    "provider_timestamp": 1767225600,
    "published_at": "2026-01-01T00:00:00.000Z",
    "expected_interval_seconds": 300,
    "lag_seconds": 5,
    "stale": false,
    "timezone": "Asia/Seoul",
    "fetched_at": "2026-01-01T00:00:05.000Z",
    "persistent_storage": true
  },
  "data": {
    "base": "USD",
    "rates": {
      "USD": 1,
      "EUR": 0.9,
      "JPY": 150
    }
  }
}

GET /api/currencies

Currency

curl --request GET 'https://staging.lumeexchangerates.com/api/currencies?lang=en' --header 'Authorization: Bearer YOUR_API_KEY'

The values and dates below illustrate response structure; they are not live rates. Arrays may show only a subset. Use the API explorer for current data.

{
  "meta": {
    "provider": "External exchange-rate provider",
    "kind": "latest_published",
    "provider_timestamp": 1767225600,
    "published_at": "2026-01-01T00:00:00.000Z",
    "expected_interval_seconds": 300,
    "lag_seconds": 5,
    "stale": false,
    "timezone": "Asia/Seoul",
    "fetched_at": "2026-01-01T00:00:05.000Z",
    "persistent_storage": true
  },
  "data": [
    {
      "code": "USD",
      "name": "US Dollar"
    },
    {
      "code": "EUR",
      "name": "Euro"
    }
  ]
}

Currency names use Intl.DisplayNames. Unrecognized assets retain their codes. Only symbols present in the latest data are returned.

GET /api/rates/history

Website-internal chart route. Accepts from/to currencies and period=1D|1W|1M|3M|1Y. 1D returns collected minute observations from the last 24 hours; other periods return UTC daily rates through yesterday. Missing minutes are not fabricated. No observations returns 503 HISTORY_NOT_COLLECTED.

Data is persisted in S3 and meta.persistent_storage is true. Historical symbol availability and provider permissions may restrict results.

GET /api/rates/previous

Previous UTC day

curl --request GET 'https://staging.lumeexchangerates.com/api/rates/previous?from=USD&to=EUR' --header 'Authorization: Bearer YOUR_API_KEY'

The values and dates below illustrate response structure; they are not live rates. Arrays may show only a subset. Use the API explorer for current data.

{
  "meta": {
    "kind": "utc_daily",
    "reference_date": "2026-01-01",
    "reference_timestamp": "2026-01-01T23:59:59Z"
  },
  "data": {
    "from": "USD",
    "to": "EUR",
    "rate": 0.9,
    "rates": {
      "USD": 1,
      "EUR": 0.9
    }
  }
}

The comparison uses the previous UTC day’s provider reference. reference_timestamp is the logical day-end boundary, not a quote’s actual publication time. Percentage change is (current − reference) / reference × 100.

POST /api/convert

Converter

curl --request POST 'https://staging.lumeexchangerates.com/api/convert' --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{"amount":100,"from":"USD","to":"EUR"}'

The values and dates below illustrate response structure; they are not live rates. Arrays may show only a subset. Use the API explorer for current data.

{
  "meta": {
    "provider": "External exchange-rate provider",
    "kind": "latest_published",
    "provider_timestamp": 1767225600,
    "published_at": "2026-01-01T00:00:00.000Z",
    "expected_interval_seconds": 300,
    "lag_seconds": 5,
    "stale": false,
    "timezone": "Asia/Seoul",
    "fetched_at": "2026-01-01T00:00:05.000Z",
    "persistent_storage": true
  },
  "data": {
    "amount": 100,
    "from": "USD",
    "to": "EUR",
    "rate": 0.9,
    "result": 90
  }
}

Send amount as a JSON number: "100" as a string returns 400. Symbols must exist in the latest snapshot. This endpoint calculates a value; it does not execute a transfer or trade.

GET /v1/history

Daily history and date-range series are available through /v1/history and /v1/series.

curl --request GET 'https://staging.lumeexchangerates.com/v1/history?date=2026-01-01&anchor=EUR&targets=USD,JPY' --header 'Authorization: Bearer YOUR_API_KEY'

The values and dates below illustrate response structure; they are not live rates. Arrays may show only a subset. Use the API explorer for current data.

{
  "meta": {
    "date": "2026-01-01",
    "published_at": "2026-01-01T23:00:00Z",
    "partial_day": false
  },
  "anchor": "EUR",
  "data": [
    {
      "currency": "USD",
      "value": 1.1
    }
  ]
}

GET /v1/series

start/end are inclusive UTC YYYY-MM-DD dates. Require start ≤ end < today UTC, with at most 366 days. anchor/targets match /v1/quotes. data[].time is the date and data[].rates maps target codes to rates. Values below illustrate the response shape.

{
  "request_id": "server-generated-uuid",
  "meta": {
    "source": "Open Exchange Rates",
    "kind": "utc_daily",
    "start": "2026-01-01",
    "end": "2026-01-02",
    "day_count": 2
  },
  "anchor": "USD",
  "data": [
    {
      "time": "2026-01-01",
      "rates": {
        "EUR": 0.9
      }
    },
    {
      "time": "2026-01-02",
      "rates": {
        "EUR": 0.91
      }
    }
  ]
}

GET /v1/candles

GET /v1/candles accepts start (a completed UTC minute), period, anchor, targets and source. Default source=observations returns collected-minute OHLC and arithmetic mean; inspect meta.samples, expected_samples and complete for gaps. Repeated publications and missing minutes are not provider tick data. source=provider requires upstream OHLC permission; otherwise 422 OHLC_NOT_IN_PLAN. Cross-currency extrema are requested from the provider, never formed by dividing independent highs/lows.

/v1/candles?start=2026-11-09T06:00:00Z&period=1h&anchor=EUR&targets=JPY&source=observations

GET /v1/capabilities

GET /v1/capabilities distinguishes implemented features from upstream availability. It describes daily-series limits, intraday observations and source-specific candle periods. It never changes the external API gate; normal key authentication and scope checks still apply.

/v1/capabilities

Data & precision

An exchange rate is useful only when its meaning is clear. Our rates are indicative references, not a bank offer or a guaranteed transaction price. Currency conversion uses a shared rate snapshot; rounding belongs at the display or settlement stage.

rate = rates[to] / rates[from]
result = amount * rate

Rates preserve floating-point precision without fixed decimal truncation. Round only for display or your accounting policy.

All rates use one source unit, including JPY. Multiply by 100 only at the display layer if needed. Account for JavaScript binary floating-point error and apply an explicit decimal and rounding policy for settlement.

Timestamps

UNIX timestamps are UTC seconds and ISO timestamps use Z. Daily UTC dates may differ from local calendar dates. The website displays latest publication time in the browser’s timezone. meta.timezone is a server display hint; it does not alter timestamp semantics.

Errors

Branch on HTTP status and error.code. Include X-Request-Id/request_id when contacting support, never keys or passwords. For 429, honor Retry-After in seconds with bounded backoff and jitter.

Limits & caching

All keys share account quotas. Second/minute windows are fixed UTC windows; monthly quota resets at 00:00 UTC on the first. Admitted requests count once, including cache hits, input errors and provider errors. Authentication/quota/preflight rejections do not count. /v1/usage reads consume no API quota.

Responses are private, no-store. Provider caching defaults to 300 seconds; publication values may repeat according to the upstream interval. X-RateLimit-*, X-Monthly-* and RateLimit headers expose limits and remaining counts. timestamp/source/stale describe the data; response_timestamp is response creation time.

Availability

Production external JSON APIs are currently disabled. Examples below require an enabled environment and a valid paid API key. Browser login alone does not authorize API calls. The website calculator remains available.

/v1/currencies, /v1/quotes, /v1/exchange, /v1/history, /v1/series, /v1/candles, /v1/capabilities, /v1/usage

API explorer

Run the request to view the real JSON response.