환율 API, 뭘 골라서 어떻게 붙일까요?

환율 API를 검색하면 후보가 여럿 나와서 처음엔 뭘 써야 할지부터 막혀요. 이 글은 그 순서대로 답해요. 먼저 실제로 고를 수 있는 무료 환율 API를 비교해 어떤 기준으로 고르면 되는지 정리하고, 고른 API를 FastAPI로 연동하는 코드, 그리고 실서비스에서 빠지기 쉬운 캐싱·예외 처리까지 이어서 다룰게요.

환율 API, 어떤 걸 써야 하나요?

결론부터 말하면, 서비스에 환율을 표시하거나 환율 계산 기능을 넣는 게 목적이라면 한국수출입은행 환율 API로 시작하는 걸 추천해요. 무료이고, 사이트에서 간단한 인증만 거치면 인증키를 받을 수 있고, 영업일마다 고시되는 매매기준율을 JSON으로 돌려줘요. 국고채 금리나 기준금리처럼 경제통계가 함께 필요하면 한국은행 경제통계시스템(ECOS) Open API가 맞아요. 둘 다 무료라서 비용이 아니라 "환율 하나면 되는가, 경제통계 시계열까지 필요한가"가 선택 기준이 돼요.

참고로 공공데이터포털에서 "한국수출입은행 환율 정보"를 검색하면 나오는 페이지는 별도 API가 아니라 같은 수출입은행 API를 안내하는 링크형 등록이에요. 어느 창구로 들어가든 결국 수출입은행에서 인증키를 받아 호출하게 되니, 실질 선택지는 위의 둘이에요.

한 가지 미리 짚어둘 게 있어요. 이 셋은 전부 고시·통계 데이터라 초 단위로 움직이는 실시간 시세가 아니에요. 환전 계산기나 가격 표시엔 충분하지만, 트레이딩처럼 실시간성이 필요한 서비스라면 유료 금융 데이터 API를 따로 검토해야 해요.

그리고 수출입은행 API는 요청 도메인이 oapi.koreaexim.go.kr로 변경됐어요(구 도메인 www.koreaexim.go.kr 경유는 2026년 4월 30일 종료). 오래된 블로그 글의 URL을 그대로 복사하면 안 되는 이유예요. 일일 호출 한도 같은 수치도 바뀔 수 있으니, 인증키를 발급받는 공식 페이지의 문서를 기준으로 확인하세요.

환율 API 연동은 어떻게 하나요?

흐름은 단순해요. 외부 API에서 환율을 받아와, 내 서비스가 쓰기 좋은 형태로 골라 응답하는 조회 엔드포인트를 하나 만드는 거예요. FastAPI를 쓰면 비동기 HTTP 클라이언트 httpx와 잘 맞고, /docs 자동 문서까지 딸려와요.

import os
 
import httpx
from fastapi import FastAPI, HTTPException
 
app = FastAPI()
 
EXIM_URL = "https://oapi.koreaexim.go.kr/site/program/financial/exchangeJSON"
API_KEY = os.environ["EXIM_API_KEY"]  # 인증키는 코드가 아니라 환경변수에
 
 
@app.get("/rates/{currency}")
async def get_rate(currency: str):
    params = {"authkey": API_KEY, "data": "AP01"}  # AP01 = 환율 데이터
    async with httpx.AsyncClient(timeout=5) as client:
        res = await client.get(EXIM_URL, params=params)
        res.raise_for_status()
    try:
        rows = res.json()
    except ValueError:
        raise HTTPException(status_code=502, detail="환율 응답을 해석하지 못했어요.")
    if not rows:  # 비영업일·고시 전엔 빈 배열이 와요
        raise HTTPException(status_code=503, detail="오늘 고시된 환율이 아직 없어요.")
    if rows[0].get("result") != 1:  # 1=성공, 그 외=인증·호출 한도 오류
        raise HTTPException(status_code=502, detail="환율 API 인증 또는 호출 한도 오류예요.")
    code = currency.upper()
    for row in rows:
        if row.get("cur_unit", "")[:3] == code:  # "JPY(100)" 같은 표기 대응
            return {"currency": code, "rate": row["deal_bas_r"]}
    raise HTTPException(status_code=404, detail="지원하지 않는 통화예요.")

응답에서 cur_unit은 통화 코드, deal_bas_r은 매매기준율이에요. 오류를 한 덩어리로 다루지 않는 게 포인트예요. HTTP는 성공해도 응답 안의 result 코드가 인증 오류나 호출 한도 초과를 알려줄 수 있고, 비영업일엔 빈 배열이 오거든요. 이걸 구분하지 않으면 인증키 문제를 "지원하지 않는 통화"로 오인하게 돼요. 통화 매칭을 앞 3글자 정확 비교로 한 것도 이유가 있어요. startswith로 느슨하게 맞추면 /rates/J 같은 요청이 엉뚱한 통화에 걸릴 수 있거든요.

한 가지 함정이 더 있어요. cur_unit이 JPY(100)처럼 괄호가 붙은 통화는 100단위 기준 환율이에요. 일본 엔(JPY)과 인도네시아 루피아(IDR)가 대표적인데, 1단위 환율로 착각하고 그대로 계산하면 100배 오류가 나요. 표시나 계산 전에 단위를 나눠 정규화해 두세요. 요청 URL과 파라미터·응답 필드는 제공처 사정으로 바뀔 수 있으니, 실제 연동 전에 인증키 발급 페이지의 공식 명세와 대조해 주세요. 인증키를 코드에 그대로 박지 않는 것도 중요해요. 커밋에 섞여 들어가면 곤란하거든요.

캐싱과 예외 처리는 왜 필요할까요?

고시 환율은 하루 한 번 갱신되는데, 요청마다 매번 외부 API로 나가는 건 낭비예요. 외부 API엔 호출 한도도 있고요. 몇 분짜리 TTL 캐시 하나만 둬도 외부 호출은 뚝 떨어지고 응답은 빨라져요.

예외 처리는 두 갈래로 준비해요. 첫째, 외부 API는 느려지거나 잠깐 죽을 수 있어요. 타임아웃을 걸고, 실패하면 마지막으로 받아둔 값을 돌려주는 fallback을 두면 내 서비스가 같이 멈추는 일을 막을 수 있어요. 둘째, 고시 환율의 특성상 주말·공휴일엔 데이터가 비어 올 수 있어요. 비영업일엔 직전 영업일 값을 쓰도록 처리해두지 않으면, 토요일마다 환율 표시가 사라지는 버그처럼 보이게 돼요.

국채 금리도 같은 패턴으로 붙일 수 있어요

국고채 수익률 같은 금리 데이터는 한국은행 ECOS Open API에서 받아요. 회원가입 후 인증키를 발급받고, 통계표 코드와 조회 기간을 파라미터로 넘기는 방식이라 위의 환율 코드에서 URL과 파라미터만 바꾸면 골격이 그대로 재사용돼요. 원하는 통계표 코드는 ECOS 사이트의 통계검색에서 찾을 수 있어요.

자주 묻는 질문

무료 환율 API 중 어떤 걸 골라야 하나요?

환율 표시·계산이 목적이면 한국수출입은행 환율 API, 금리·국채 등 경제통계가 필요하면 ECOS예요. 공공데이터포털의 환율 정보 페이지는 같은 수출입은행 API를 안내하는 링크형 등록이라 실질 선택지는 이 둘이고, 둘 다 무료라 비용 차이는 없어요.

무료 호출 한도는 얼마나 되나요?

제공처마다 일 단위 한도가 있고 수치는 바뀔 수 있어서, 인증키 발급 페이지의 공식 문서 확인이 가장 정확해요. 어차피 고시 환율은 하루 한 번 갱신이라, TTL 캐시를 두면 한도가 병목이 될 일은 거의 없어요.

환율은 얼마나 자주 갱신되나요?

영업일마다 한 번 고시되는 일 단위 데이터예요. 실시간 시세가 아니므로 용도에 따라 유료 API가 필요할 수 있고, 주말·공휴일엔 데이터가 비어 올 수 있어요.

국채 금리 데이터는 어디서 받나요?

한국은행 ECOS Open API에서 국고채 수익률을 비롯한 금리 시계열을 무료로 조회할 수 있어요.

정리

처음부터 여러 통화와 지표를 다 넣으려 하지 마세요. 엔드포인트 하나가 제대로 도는 걸 확인한 뒤 하나씩 늘려가면 돼요. 작은 캐시와 fallback 한 겹이 운영 부담을 확실히 줄여줘요. 생활 속 환율·금액 계산이 필요하다면 라이프케어로그의 생활 계산기 플랜씨(plan-c)도 살펴보세요.