공개 코인 캔들 수집: 페이지 이동·빈 구간·완료 봉 보관 OnTech Insight

TECH INSIGHT / EXPLAINED

공개 캔들 API는 학습과 재현 가능한 연구에 유용합니다. 행을 받는 것 외에도 출처·페이지 경계·시간대·빈 구간·마지막 봉 완료 여부를 기록해야 합니다.

AI로 제작한 설명용 일러스트. 세 사람이 페이지를 넘기고 중복을 확인하며 미완료 봉을 UTC 보관본에서 분리합니다.

먼저 범위를 제한한 한 페이지

업비트 한국의 GET /v1/candles/minutes/60은 market=KRW-BTC와 최대 200의 count를 받습니다. 현재 분 단위에는 1·3·5·10·15·30·60·240이 포함됩니다. 타임아웃·HTTP/JSON 검증·공유 호출 제한 조율을 적용하세요.

to는 해당 시각 이전 봉을 선택합니다. UTC를 명시하고 반환된 가장 오래된 봉을 찾아 다음 커서가 반드시 과거로 이동하는지 검사합니다. 빈 응답·목표 시작일·페이지 상한에서 종료하세요. 응답 순서를 확인 없이 가정하지 않습니다.

체결이 없으면 봉도 없을 수 있다

업비트는 체결이 있는 시간 구간에 캔들을 만들므로 빈 구간이 곧 수집 실패는 아닙니다. 이 차이를 보존해야 합니다. 빈 봉을 합성하는 정책은 지표 입력을 바꾸므로 기록하고, 거래가 있었던 것처럼 조용히 채우지 않습니다.

아래 정규화 예제는 완료된 1시간 봉 선택과 충돌 중복 검출을 보여줍니다. 완전한 수집기나 OHLC 검증기는 아닙니다. 실제 가격·거래량은 내보내기 전에 유한 값과 범위 검사가 더 필요합니다.

from datetime import datetime, timedelta, timezone
def normalize_hourly(rows, market, now):
    if now.tzinfo is None:
        raise ValueError('aware now required')
    unique = {}
    for row in rows:
        if row['market'] != market:
            raise ValueError('market mismatch')
        # This field is explicitly UTC in the API schema.
        start = datetime.fromisoformat(row['candle_date_time_utc']).replace(tzinfo=timezone.utc)
        if start + timedelta(hours=1) > now:
            continue  # exclude the still-open candle
        if start in unique and unique[start] != row:
            raise ValueError('conflicting duplicate candle')
        unique[start] = dict(row)
    return [(t, unique[t]) for t in sorted(unique)]

sample = {'market':'KRW-BTC','candle_date_time_utc':'2026-09-29T00:00:00','trade_price':100}
now = datetime(2026,9,29,1,30,tzinfo=timezone.utc)
assert len(normalize_hourly([sample,sample],'KRW-BTC',now)) == 1

거래소별 스키마 분리

Binance Spot /api/v3/klines는 다른 배열 스키마이며 한 번에 최대 1,000행을 지원합니다. 봉 시작 시각이 봉을 식별합니다. 타임스탬프 단위와 설정한 구간 시간대는 해당 API 규칙대로 해석하세요. BTCUSDT와 업비트 KRW-BTC를 같은 통화 가격열처럼 합치면 안 됩니다.

제공되는 소수 문자열은 원본에 보존하고 분석용 변환을 명시적으로 합니다. 거래소·시장·봉 간격·UTC 시작 시각을 키로 정렬·중복 제거합니다. 페이지 중복은 대비할 조건이지 배타적 커서에서도 매번 경계가 중복된다는 뜻은 아닙니다.

재현 가능한 보관본 만들기

오프셋을 포함한 UTC 시각·OHLCV·거래소·간격·수집 시각을 내보냅니다. 정규화 CSV 옆에 요청 파라미터와 원본 페이지를 보관하세요. 같은 키의 두 값이 다르면 한쪽을 조용히 선택하지 말고 원인을 확인할 자료를 보존합니다.

고정 sleep은 로컬 속도 조절일 뿐 공유 한도 준수를 보장하지 않습니다. 현재 한도와 접근·재배포 조건을 따르세요. 공개 자료라는 이유만으로 무한 과거 이력·자유로운 재배포·주문 대기열 시뮬레이션에 필요한 상세도가 보장되지는 않습니다.

공식 자료와 함께 읽기

Upbit minute candles · Binance Spot klines · Upbit rate limits

내용·예제 검토: 2026-09-29

공개 코인 캔들 수집: 페이지 이동·빈 구간·완료 봉 보관