LUME EXCHANGE RATES / API REFERENCE

API 문서

현재 설정된 데이터 출처는 외부 환율 데이터 공급사입니다. 최신 환율 응답에는 출처와 공급사 발표시각을 담고, 실제 응답에 존재하는 통화 코드를 제공합니다. 제공 가능한 통화는 최신 데이터에 맞춰 갱신됩니다.

Base URLhttps://staging.lumeexchangerates.com

서비스 개요

Lume Exchange Rates는 환율 비교, 통화 변환, 과거 추이를 한곳에서 확인할 수 있는 글로벌 환율 서비스입니다. 여행 예산을 세우거나 해외 가격을 비교할 때, 또는 제품에 환율을 연결할 때 필요한 두 통화를 직접 선택해 살펴보세요.

현재 설정된 데이터 출처는 외부 환율 데이터 공급사입니다. 최신 환율 응답에는 출처와 공급사 발표시각을 담고, 실제 응답에 존재하는 통화 코드를 제공합니다. 제공 가능한 통화는 최신 데이터에 맞춰 갱신됩니다.

HTTPSJSONUTF-8GET / POSTUTC

빠른 시작

현재 운영 외부 JSON API는 비활성화되어 있습니다. 아래 예제는 API가 활성화된 환경에서 유효한 유료 API 키로 실행합니다. 로그인만으로 호출 권한이 생기지 않습니다. 웹 환율 계산기는 이용할 수 있습니다.

cURL
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"
JavaScript · server
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);

접근과 인증

고객 키는 /account에서 관리합니다. 활성 유료 구독과 서버에서 확인된 결제가 있어야 키 발급 및 환율 API 이용이 가능합니다. 구독이 없는 계정에는 무료 API 한도가 없습니다. 공급사 App ID는 서버에만 보관합니다.

Authentication
Authorization: Bearer lume_…
PermissionAccess
rates:read/v1/currencies, /v1/quotes, /v1/exchange, /v1/history, /v1/series, /v1/candles, /v1/capabilities
usage:read/v1/usage?range=today|7d|30d
Owner session/api/usage, account and support management

비밀 키는 서버에 보관하세요. IP·도메인 제한을 설정하면 모든 조건을 만족해야 합니다. 교차 출처 요청은 운영자가 명시적으로 허용한 HTTPS Origin에만 선택적으로 열립니다. CORS는 인증을 대체하지 않습니다.

엔드포인트

GET endpointParameters
/v1/currencies—
/v1/quotesanchor, targets
/v1/exchangefrom, to, quantity
/v1/historydate, anchor, targets
/v1/seriesstart, end, anchor, targets
/v1/candlesstart, period, anchor, targets, source
/v1/capabilities—
/v1/usagerange=today|7d|30d

GET /v1/currencies

현재 환율이 있는 모든 코드와 공급사 통화명을 반환합니다. 제공 가능한 대체 통화와 귀금속도 포함됩니다.

파라미터: —

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

아래 숫자와 날짜는 응답 구조를 설명하기 위한 예시이며 현재 시세가 아닙니다. 배열은 일부 항목만 보여줍니다. 실제 값은 API 실행기에서 확인하세요.

JSON
{
  "meta": {
    "mode": "provider",
    "source": "외부 환율 데이터 공급사",
    "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"
    }
  ]
}
파라미터자료형설명
data[].codestring대문자 통화 코드. 대체 자산은 3자를 초과하거나 밑줄이 포함될 수 있습니다.
data[].namestring공급사 이름. 이름이 없으면 코드 자체를 반환합니다.

GET /v1/quotes

기준 통화. 기본값 USD이며 현재 공급사가 지원하는 모든 코드를 사용할 수 있습니다.

파라미터자료형필수기본값설명
anchorstring선택USD기준 통화. 기본값 USD이며 현재 공급사가 지원하는 모든 코드를 사용할 수 있습니다.
targetsstring선택전체쉼표로 구분한 대상 통화 코드. 생략하면 지원되는 모든 통화를 반환합니다.
cURL
curl --request GET 'https://staging.lumeexchangerates.com/v1/quotes?anchor=USD&targets=EUR,JPY' --header 'Authorization: Bearer YOUR_API_KEY'

아래 숫자와 날짜는 응답 구조를 설명하기 위한 예시이며 현재 시세가 아닙니다. 배열은 일부 항목만 보여줍니다. 실제 값은 API 실행기에서 확인하세요.

JSON
{
  "meta": {
    "mode": "provider",
    "source": "외부 환율 데이터 공급사",
    "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
    }
  ]
}

예: /v1/quotes?anchor=EUR&targets=USD,JPY. value는 기준 통화 1단위당 대상 통화 값입니다. 중복 targets는 제거되며 빈 코드, 소문자, 현재 시세에 없는 코드는 400을 반환합니다.

파라미터자료형설명
anchorstring기준 통화. 기본값 USD이며 현재 공급사가 지원하는 모든 코드를 사용할 수 있습니다.
data[].currencystring비교 통화
data[].valuenumberrates[currency] / rates[anchor]

GET /v1/exchange

변환할 금액. 0 이상의 숫자를 입력합니다.

파라미터자료형필수기본값설명
fromstring선택USD변환 전 통화 코드. 기본값 USD.
tostring선택EUR변환할 대상 통화 코드. 기본값 EUR.
quantitynumber선택1변환할 금액. 0 이상의 숫자를 입력합니다.
cURL
curl --request GET 'https://staging.lumeexchangerates.com/v1/exchange?from=USD&to=EUR&quantity=100' --header 'Authorization: Bearer YOUR_API_KEY'

아래 숫자와 날짜는 응답 구조를 설명하기 위한 예시이며 현재 시세가 아닙니다. 배열은 일부 항목만 보여줍니다. 실제 값은 API 실행기에서 확인하세요.

JSON
{
  "meta": {
    "mode": "provider",
    "source": "외부 환율 데이터 공급사",
    "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
  }
}

예: /v1/exchange?from=USD&to=EUR&quantity=100. 전 세계 사용자의 혼동을 피하려면 from과 to를 항상 명시하세요. 이 기존 GET 경로의 to 기본값은 EUR입니다. 빈 값, 음수, NaN, 무한대 또는 계산 결과 오버플로는 400입니다.

파라미터자료형설명
data.ratenumberrates[to] / rates[from]
data.resultnumberquantity × rate

GET /api/rates/latest

최신 발표환율

파라미터: —

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

아래 숫자와 날짜는 응답 구조를 설명하기 위한 예시이며 현재 시세가 아닙니다. 배열은 일부 항목만 보여줍니다. 실제 값은 API 실행기에서 확인하세요.

JSON
{
  "meta": {
    "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
    }
  }
}
파라미터자료형설명
data.basestringUSD
data.ratesobjectUSD 기준 전체 환율. 존재 여부는 최신 응답으로 확인합니다.
meta.provider_timestampintegerUTC · UNIX seconds
meta.published_atstringISO 8601 · UTC
meta.fetched_atstring서버가 데이터를 가져온 시각. 공급사 발표시각과 다릅니다.
meta.expected_interval_secondsintegerseconds
meta.staleboolean예상 주기 3배와 900초 중 더 긴 시간보다 시세가 오래되면 true.
meta.lag_secondsinteger공급사 발표 이후 경과 초.
meta.persistent_storageboolean영구 수집 서비스 연결 여부.
meta.kindstringlatest_published | utc_daily

GET /api/currencies

통화

파라미터자료형필수기본값설명
langstring선택enen / ko / ja / zh / es / hi / bn / de / fr / nl / pt / it / ru / vi / th / ar / id / ur
cURL
curl --request GET 'https://staging.lumeexchangerates.com/api/currencies?lang=en' --header 'Authorization: Bearer YOUR_API_KEY'

아래 숫자와 날짜는 응답 구조를 설명하기 위한 예시이며 현재 시세가 아닙니다. 배열은 일부 항목만 보여줍니다. 실제 값은 API 실행기에서 확인하세요.

JSON
{
  "meta": {
    "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"
    }
  ]
}

통화명은 Intl.DisplayNames로 현지화합니다. 이름을 구할 수 없는 자산은 코드로 표시합니다. 최신 데이터에 있는 코드만 반환합니다.

GET /api/rates/history

웹사이트 내부 차트 경로입니다. from·to 통화와 period=1D|1W|1M|3M|1Y를 받습니다. 1D는 최근 24시간 동안 실제로 수집한 분 관측값이며, 다른 기간은 어제까지의 UTC 일별 값입니다. 누락된 분을 임의로 만들지 않습니다. 기록이 없으면 503 HISTORY_NOT_COLLECTED입니다.

S3에 저장하며 meta.persistent_storage는 true입니다. 과거 통화 지원 여부와 공급사 권한에 따라 조회가 실패할 수 있습니다.

GET /api/rates/previous

직전 UTC 날짜

파라미터자료형필수기본값설명
fromstring선택USD기준 통화
tostring선택EUR비교 통화
cURL
curl --request GET 'https://staging.lumeexchangerates.com/api/rates/previous?from=USD&to=EUR' --header 'Authorization: Bearer YOUR_API_KEY'

아래 숫자와 날짜는 응답 구조를 설명하기 위한 예시이며 현재 시세가 아닙니다. 배열은 일부 항목만 보여줍니다. 실제 값은 API 실행기에서 확인하세요.

JSON
{
  "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
    }
  }
}

직전 UTC 날짜의 공급사 일별 값을 비교 기준으로 사용합니다. reference_timestamp는 해당 UTC 날짜의 논리적 마감 경계이며 개별 시세의 실제 발표시각이 아닙니다. 등락률은 (현재값 − 기준값) / 기준값 × 100입니다.

POST /api/convert

환율 계산기

파라미터자료형필수기본값설명
Content-Typeheader필수application/jsonapplication/json
amountnumber필수—0 ≤ amount ≤ 1e15; finite
fromstring필수—기준 통화
tostring필수—비교 통화
cURL
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"}'

아래 숫자와 날짜는 응답 구조를 설명하기 위한 예시이며 현재 시세가 아닙니다. 배열은 일부 항목만 보여줍니다. 실제 값은 API 실행기에서 확인하세요.

JSON
{
  "meta": {
    "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
  }
}

JSON 본문의 숫자를 사용합니다. amount: "100"처럼 문자열로 보내면 400입니다. 선택 통화는 최신 환율 집합에 있어야 하며 응답은 실제 송금이나 거래를 실행하지 않습니다.

GET /v1/history

과거 날짜 환율은 /v1/history, 기간별 시계열은 /v1/series로 조회합니다.

파라미터자료형필수기본값설명
dateYYYY-MM-DD필수—1999-01-01 ≤ date < UTC today
anchorstring선택USD기준 통화
targetsCSV선택all비교 통화
cURL
curl --request GET 'https://staging.lumeexchangerates.com/v1/history?date=2026-01-01&anchor=EUR&targets=USD,JPY' --header 'Authorization: Bearer YOUR_API_KEY'

아래 숫자와 날짜는 응답 구조를 설명하기 위한 예시이며 현재 시세가 아닙니다. 배열은 일부 항목만 보여줍니다. 실제 값은 API 실행기에서 확인하세요.

JSON
{
  "meta": {
    "date": "2026-01-01",
    "published_at": "2026-01-01T23:00:00Z",
    "partial_day": false
  },
  "anchor": "EUR",
  "data": [
    {
      "currency": "USD",
      "value": 1.1
    }
  ]
}
파라미터자료형설명
meta.partial_daybooleanUTC 일별 기준환율
meta.published_atISO 8601 UTC최신 발표환율

GET /v1/series

start·end는 UTC YYYY-MM-DD이며 양 끝 날짜를 포함합니다. start ≤ end < 오늘(UTC), 최대 366일입니다. anchor와 targets는 /v1/quotes와 같습니다. data[].time은 날짜이며 data[].rates는 대상 코드별 환율 객체입니다. 아래 값은 형식 설명용 예제입니다.

JSON
{
  "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는 start(완료된 UTC 분), period, anchor, targets, source를 받습니다. source=observations가 기본이며 수집된 분 관측값의 OHLC·산술평균입니다. meta.samples, expected_samples, complete로 누락 여부를 확인합니다. 공급사 발표 사이의 반복값과 누락 분을 실제 틱으로 간주하지 않습니다. source=provider는 공급사 OHLC 권한이 필요하며 없으면 422 OHLC_NOT_IN_PLAN입니다. 독립적인 두 통화의 고가·저가를 나눠 교차통화 OHLC를 만들지 않습니다.

GET
/v1/candles?start=2026-11-09T06:00:00Z&period=1h&anchor=EUR&targets=JPY&source=observations
SourcePeriods
observations1m, 5m, 15m, 30m, 1h, 12h, 1d
provider1m, 5m, 15m, 30m, 1h, 12h, 1d, 1w, 1mo; provider history/alignment limits apply

GET /v1/capabilities

GET /v1/capabilities는 구현 여부와 공급사 권한을 구분해 반환합니다. 일별 시계열의 최대 일수, 일중 관측 범위, OHLC 소스별 지원 기간을 확인할 수 있습니다. API 차단 설정을 변경하지 않으며, 기존 키 인증·권한 검증을 그대로 적용합니다.

GET
/v1/capabilities

데이터와 정밀도

환율의 의미와 시점을 알 수 있어야 올바르게 활용할 수 있습니다. 제공 환율은 은행의 매매 가격이나 거래가 보장된 호가가 아닌 참고용 기준환율입니다. 통화 변환은 동일한 환율 집합으로 계산하고, 반올림은 화면 표시나 정산 단계에서 적용합니다.

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

환율은 소수 자릿수를 고정해 잘라내지 않습니다. 화면 표시나 회계 정책에 맞춰 최종 단계에서 반올림하세요.

통화 1단위 기준으로 계산하며 엔화도 동일합니다. 100엔 표시가 필요하면 최종 표시 단계에서만 100을 곱하세요. JavaScript number의 이진 부동소수점 오차를 고려하고, 회계 정산에서는 별도의 소수점·반올림 정책을 적용하세요.

시각과 날짜

UNIX 시각은 UTC 초, ISO 날짜·시각은 UTC의 Z 표기를 사용합니다. 일별 날짜는 사용자의 현지 날짜와 다를 수 있습니다. 웹사이트는 최신 발표시각을 사용자의 브라우저 시간대로 표시합니다. /api의 meta.timezone은 서버 표시 힌트이며 UTC timestamp의 기준을 변경하지 않습니다.

파라미터자료형설명
/v1 meta.as_ofISO 8601 | YYYY-MM-DD공급사 기준시각
/v1 meta.refresh_interval_secondsinteger캐시
/v1 meta.currency_countinteger현재 …개 통화 지원
/v1 meta.modeprovider | daily데이터 출처
/api meta.published_atISO 8601 UTC최신 발표환율
history data[].timeYYYY-MM-DD UTC | UNIX secondsUTC 일별 기준환율

오류 처리

HTTPerror.code
400INVALID_PARAMETER / INVALID_CURRENCY / INVALID_CONVERSION / INVALID_JSON / INVALID_DATE / INVALID_DATE_RANGE
401INVALID_API_KEY / AUTH_REQUIRED
403SUBSCRIPTION_REQUIRED / SCOPE_NOT_ALLOWED / IP_NOT_ALLOWED / DOMAIN_NOT_ALLOWED
404NOT_FOUND / OBSERVATIONS_NOT_COLLECTED
422OHLC_NOT_IN_PLAN / CANDLE_HISTORY_UNAVAILABLE / FEATURE_UNAVAILABLE
405METHOD_NOT_ALLOWED
429RATE_LIMIT_EXCEEDED / MONTHLY_LIMIT_EXCEEDED
503API_NOT_AVAILABLE / PROVIDER_UNAVAILABLE / SERVICE_UNAVAILABLE

HTTP 상태와 error.code로 분기합니다. X-Request-Id와 request_id를 문의에 첨부할 수 있습니다. 429는 Retry-After(초)를 따르고 지수 백오프와 임의 지연을 적용하세요. 키나 비밀번호는 문의에 넣지 마세요.

제한과 캐시

PlanMonthly UTCPer secondPer minute
Launch10000560
Scale10000020300
UnlimitedUnlimited501200

모든 키가 계정 한도를 공유합니다. 초·분은 고정 UTC 창이며, 월 한도는 매월 1일 00:00 UTC에 초기화됩니다. 승인된 요청은 캐시 적중·입력 오류·공급사 오류도 1회로 집계합니다. 인증·쿼터·승인 전 검증 거절은 집계하지 않습니다. /v1/usage 조회는 무료이며 호출 한도를 소비하지 않습니다.

응답은 private, no-store입니다. 공급사 캐시는 기본 300초이며 실제 갱신 주기에 따라 같은 발표값이 반복될 수 있습니다. X-RateLimit-*·X-Monthly-*·RateLimit 헤더에서 한도와 잔여량을 확인하세요. timestamp·source·stale은 데이터 기준이고 response_timestamp는 응답 생성 시각입니다.

제공 범위

현재 운영 외부 JSON API는 비활성화되어 있습니다. 아래 예제는 API가 활성화된 환경에서 유효한 유료 API 키로 실행합니다. 로그인만으로 호출 권한이 생기지 않습니다. 웹 환율 계산기는 이용할 수 있습니다.

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

API 실행기

이 사이트의 API를 직접 호출해보세요. 공급사 키는 서버에서 보호됩니다.

요청 / cURL
응답 / JSON
요청을 실행하면 실제 JSON 응답을 확인할 수 있습니다.


SUBSCRIPTION / USD
구독 내용 확인
USD 정기구독입니다. 최종 세금과 총액은 보안 결제창에서 확인한 후 승인하세요.
적용 세금은 결제창에 표시됩니다. 결제 포털에서 구독 갱신을 관리하고 취소할 수 있습니다.
Paddle


ACCOUNT / BILLING
내 구독