Kumo Charts

시세 데이터

메서드 4개만 구현하면 어떤 시세 서버에도 연결할 수 있습니다:

import type { Datafeed } from '@kumo-charts/pro-chart';

const myDatafeed: Datafeed = {
  // 서버가 줄 수 있는 봉 주기. 다른 주기는 차트가 합성합니다: 5m, 15m은 1m으로, 1W, 1M은 1D로.
  intervals: ['1m', '1D'],

  // 모르는 종목이거나 잠시 가져올 수 없을 때는 거부합니다. 거부하면 차트는 이 종목을 그대로 두고 불러오기 실패를 표시하며 다시 시도할 수 있고, 다른 종목으로 바꾸지 않습니다.
  resolveSymbol: (id) => api.symbol(id),

  // 시간순(오래된 것부터)으로. before가 있으면 그 이전의 봉(사용자가 왼쪽으로 끌 때 더 이전 데이터를 불러옴)을 주고, 빈 배열은 더 이전 것이 없다는 뜻입니다.
  getBars: ({ symbol, interval, limit, before }) => api.klines(symbol, interval, limit, before),

  // 실시간 데이터: 체결이 있으면 trades를, 봉만 있으면 bars를 줍니다(형성 중인 봉이 바뀔 때마다 다시 한 번).
  // 체결에 공격자 측 side('buy'는 매도 주문을 사고, 'sell'은 매수 주문에 팖)가 있어야 풋프린트와 오더 플로우 지표를 쓸 수 있습니다.
  subscribe(symbol, interval, listener) {
    const socket = api.stream(symbol, (message) => listener.trades(message.trades));
    return () => socket.close();
  },

  // 선택: 과거 체결을 분 단위로(아래 "과거 체결" 참고). 풋프린트, 오더 플로우 지표, 대량 체결이 이것으로 차트를 열기 전의 봉을 채웁니다.
  // 이것이 없으면 오더 플로우 지표가 없습니다.
  getTradeMinutes: ({ symbol, from, to, parts, signal }) =>
    api.tradeMinutes(symbol, from, to, parts, signal), // { covered, tickSize, minutes }

  // 선택: 호가창. 호가창 히트맵에 씁니다. 대략 1초마다 스냅샷을 보내고, 호가마다 [가격, 수량]. 막 구독했을 때는 최근 구간의 몇 장을 먼저 보낼 수 있습니다.
  subscribeBook(symbol, listener) {
    const socket = api.depth(symbol, (book) => listener([book])); // [{ time, bids: [[가격, 수량]], asks }]
    return () => socket.close();
  },

  // 선택: 상단 바의 종목 검색에 씁니다. type은 시장 분류, exchange는 플랫폼 이름이며, 사용자가 골랐을 때만 값이 있습니다.
  searchSymbols: (query, type, exchange) => api.search(query, type, exchange), // [{ id: '600519.SH', name: '구이저우마오타이', description: '상하이증권거래소' }]

  // 선택: 종목이 있는 플랫폼. 두 개 이상이면 검색 창 왼쪽에 플랫폼을 나열해 그중 하나만 검색할 수 있습니다.
  exchanges: [{ name: '상하이증권거래소', logo: '/icons/sse.svg' }, { name: '선전증권거래소' }]
};
  • 주기: intervals는 데이터 피드가 가진 봉 주기이고, 다른 주기는 차트가 그것으로 합성합니다(15m은 1m으로, 4h는 1h로). 시세 출처가 사용자가 연 뒤에야 생기는 페이지(예를 들어 플러그인을 열 때 추가되는 경우)는 intervals를 처음엔 비워 둘 수 있습니다. 그동안은 페이지가 준 주기를 모두 표시하고, 저장된 주기도 기본값으로 되돌리지 않으며, 종목이 자기 주기(SymbolInfo.intervals)를 알려 주면 그것을 따릅니다.

  • 종목 검색: 데이터 피드에 searchSymbols가 있어야 상단 바에 검색이 있습니다. 없으면 페이지가 setSymbol()로 종목을 바꿉니다. features.symbolSearch를 true로 했는데 데이터 피드에 searchSymbols가 없으면 오류가 납니다.

  • 종목 정보 SymbolInfo: id, name은 필수입니다. name은 상단 바와 목록에 표시하는 이름이며, 슬래시가 있는 것(BTC/USDT)은 슬래시 뒤의 견적 통화를 흐리게 표시합니다. market은 거래 방식(spot 현물, perpetual 무기한 계약)이며 이름 뒤에 작은 태그(현물, 무기한)를 표시합니다. inverse: true인 계약은 거래하는 코인으로 증거금과 정산을 하며(코인 마진), 태그는 코인 마진이 됩니다. market을 주지 않으면 태그가 없습니다. description은 검색 결과의 두 번째 줄입니다(언어별로 { en, zh, ja, ko }로 줄 수 있으며, en은 필수이고 주지 않은 언어에서는 en을 표시합니다). type은 시장 분류(forex, metal, energy, crypto, stock, etf, other)이며 검색이 이것으로 거릅니다. exchange는 소속 플랫폼이며, 모든 플랫폼을 검색할 때 결과에 플랫폼 이름과 아이콘을 표시합니다(아이콘은 데이터 피드 exchanges에 있는 같은 이름 플랫폼의 logo). logos는 아이콘으로 자산마다 하나(외환 같은 페어는 두 개, 기준 통화가 위), 각각 주소 하나이거나 차례로 시도할 여러 주소입니다. 아이콘이 없거나 모두 불러오지 못하면 이름의 첫 글자를 표시합니다. pricePrecision은 가격의 소수 자릿수이며, 주지 않으면 봉에서 읽습니다. tickSize는 최소 가격 변동(예: 0.1)으로, 볼륨 풋프린트와 시간 가격 기회의 "행당 틱"을 이것으로 셉니다. 주지 않으면 소수 자릿수의 마지막 자리를 씁니다. intervals는 이 종목 자체의 봉 주기로, 데이터 피드의 것과 다를 때 줍니다. calendar는 거래 캘린더로, 주기 합성은 이것으로 나눕니다. 예를 들어 중국 A주는:

    { timeZone: 'Asia/Shanghai', sessions: ['09:30-11:30', '13:00-15:00'], weekdays: [1, 2, 3, 4, 5] }

    주지 않으면 암호화폐 거래소와 같이 UTC 시간대로 하루 24시간 거래로 봅니다.

  • 과거 체결 getTradeMinutes(request): 이것을 줘야 오더 플로우 지표(VD, CVD, UDV)와 시장가 매수·매도로 나눈 매물대이 생기고, 풋프린트와 대량 체결에 차트를 열기 전의 것이 생깁니다. 오더 플로우가 1분마다 쓰는 것은 이 몇 가지뿐이라서, 체결을 하나하나 주지 않고 분 단위로 요청하고 분 단위로 줍니다:

    • 요청 { symbol, from, to, parts, signal }: [from, to)의 1분마다이며, from, to는 모두 정각 분(60000의 배수)이고, to는 늦어도 몇 초 전에 끝난 1분까지입니다(끝나고 5초 뒤에 요청합니다. 플랫폼이 체결을 조금 늦게 공개하기 때문입니다). parts는 합계 말고 무엇이 더 필요한지로, 'levels'(가격별 거래량, 풋프린트와 시장가 매수·매도로 나눈 매물대에 사용)와 'large'(거래대금이 가장 큰 몇 건, 대량 체결에 사용)가 있습니다. 합계만 필요하면 비어 있습니다(VD, CVD, UDV는 합계만 씁니다). 합계만 요청하는 것은 한 번에 최대 3일(일봉의 30일 CVD는 요청 10개), levels나 large가 있는 것은 한 번에 최대 6시간이며, 최신 것부터 요청하고 동시에 진행 중인 요청은 최대 두 개입니다. 차트가 더 이상 필요하지 않으면 signal로 중단합니다.

    • 응답 { covered, tickSize, minutes }: minutes는 covered 안에서 체결이 있는 분이며 오래된 것이 먼저이고, 체결이 없는 분은 쓰지 않습니다. 1분마다 { time, buy, sell, count, levels?, large? }이며, time은 그 분의 시작, buy, sell은 시장가 매수·매도 거래량(기초 자산 기준, 체결 수량과 같은 단위), count는 체결 건수입니다. levels를 요청했으면 levels는 [가격, 매수량, 매도량, 가격, …]이며, 가격은 낮은 것부터, 가격마다 한 번씩, tickSize의 격자 위에 있습니다. large를 요청했으면 large는 그 분의 거래대금(가격 × 수량)이 가장 큰 최대 32건의 [시간, 가격, 수량, 방향, …]이며, 방향 1은 시장가 매수, -1은 시장가 매도입니다. 큰 것이 먼저이고, 같으면 이른 것이 먼저이며, 1분에 32건이 안 되면 모두 줍니다.

    • covered는 [from, to) 가운데 체결이 온전한 구간 [[시작, 끝], …]입니다. 모두 있으면 [[from, to]], 1분도 없으면 []입니다. 플랫폼(또는 여러분의 서버)이 어떤 시간 동안 체결이 없거나 다 받지 못했으면(그때 받고 있지 않았거나, 연결이 끊겼거나, 이미 보관하지 않음) 그 앞뒤를 여러 구간으로 나누고 오래된 것을 먼저 씁니다. 어떤 구간 안에 통째로 들어가는 분만 온전한 것으로 보며, 그 안에서 쓰지 않은 분은 체결이 없는 것으로 봅니다. 어느 구간에도 들어가지 않는 분은 "체결 없음"으로 보고, 이후 다시 묻지 않습니다. 1분은 그 체결이 하나도 빠짐없이 있을 때만 covered에 넣을 수 있습니다. 그렇지 않으면 차트에 틀린 숫자가 그려집니다. 중간에 끊긴 몇 분은 넣지 않고 앞뒤의 온전한 분은 그대로 넣으면, 끊긴 부분의 봉만 "체결 없음"이 됩니다.

    • tickSize는 levels 가격의 간격으로, 종목의 최소 가격 변동이거나 0(가격 그대로)입니다. 차트는 각 가격을 종목의 tickSize에 맞춰 놓으므로(같은 칸에 들어가는 것은 합산), 종목의 것과 같거나 더 촘촘해야 합니다.

    • 가져올 수 없으면 돌려준 Promise를 거부합니다. 차트는 5초 뒤에 다시 묻고, 매번 대기 시간을 두 배로 늘려 최대 80초까지 기다리며, 그동안 그 봉은 "실패"로 표시합니다. 지금은 줄 수 없지만 언제 줄 수 있는지 알 때(예를 들어 서버가 아직 체결로 이 분들을 계산하고 있을 때)는 거부하는 오류에 retryAfter(밀리초)를 붙입니다. 이는 실패로 치지 않으며, 그 봉은 "불러오는 중"으로 표시되고, 차트는 그 시간이 되면 같은 구간을 다시 묻습니다. 대기 시간을 늘리지 않으며, 체결이 없는 것으로 보지도 않습니다.

    • 체결을 가지고 있다면 tradeMinutes(trades, tickSize, parts)로 분을 합성합니다(체결에 side 포함). 차트가 푸시받은 체결로 직접 저장하는 것과 완전히 같습니다:

      import { tradeMinutes } from '@kumo-charts/pro-chart';
      
      getTradeMinutes: async ({ symbol, from, to, parts, signal }) => {
        const trades = await api.trades(symbol, from, to, signal); // [{ time, price, size, side }]
        return { covered: [[from, to]], tickSize: 0.1, minutes: tradeMinutes(trades, 0.1, parts) };
      };
  • 호가창 subscribeBook(symbol, listener): 이것을 줘야 호가창 히트맵(지표 창 "오더 플로우" 그룹의 BOOKHEATMAP)이 생깁니다. listener는 스냅샷 { time, bids, asks }의 배열을 받습니다. time은 밀리초이고, bids, asks는 [가격, 수량]의 호가입니다(수량은 기초 자산 기준, 순서는 상관없음). 한쪽의 깊이는 준 것 중 가장 깊은 호가까지이며, 수량이 0인 호가는 거기에 주문이 없고 거기까지는 알고 있다는 뜻입니다. 주문이 있는 호가만 주면 가장 깊은 호가 너머는 모르는 것으로 보고 그리지 않습니다. 차트는 초 단위로 저장하고(1초에 여러 장이면 마지막 한 장만 남김), 같은 종목의 여러 차트는 호가창 하나와 구독 하나를 함께 쓰며, 마지막 히트맵을 닫으면 구독을 해지합니다. 거래소는 과거 호가창을 제공하지 않으므로 히트맵은 구독을 시작한 뒤부터만 있습니다. 막 구독했을 때 서버가 가지고 있는 최근 구간(예를 들어 최근 2분)을 먼저 보내면 페이지를 새로 고친 뒤에도 비어 있지 않습니다.

  • 차트는 현재 표시 중인 종목과 주기를 구독하고, 바뀌면 이전 것의 구독을 해지합니다. 알림이 있는 종목도 구독합니다. "알림"을 참고하세요. 같은 종목과 주기는 한 번만 구독하며, 차트와 알림이 함께 씁니다.

  • 차트는 먼저 구독하고 나서 최신 봉을 요청합니다(그래서 subscribe()가 getBars()보다 먼저 호출됩니다). 봉이 아직 오는 중일 때 푸시된 체결과 봉은 일단 저장해 두었다가, 봉이 도착하면 받은 순서대로 이어 붙이므로 형성 중인 봉에 빠지는 체결이 없고, 그동안 완성된 봉도 최종 값이 됩니다. 체결만 푸시하는 데이터 피드는 어떤 체결이 이미 돌려준 마지막 봉에 포함되었는지 구분할 수 없으므로, 이 사이의 몇 건의 체결 거래량이 두 번 계산될 수 있습니다.

프로 차트에는 거래소나 다른 플랫폼의 데이터 피드가 포함되어 있지 않습니다. 임베드하는 페이지에는 각자의 시세가 있으므로, 위의 인터페이스대로 연결하면 됩니다.

↑↓ 선택 · Enter 열기 · Esc 닫기