Kumo Charts

相場データ

4 つのメソッドを実装すれば、どんな相場サーバーにもつなげられます:

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

const myDatafeed: Datafeed = {
  // サーバーが提供できる足の時間足。それ以外はチャートが合成します:5m と 15m は 1m から、1W と 1M は 1D から。
  intervals: ['1m', '1D'],

  // 知らない銘柄や、一時的に取得できないときは reject します。reject されるとチャートはその銘柄のまま読み込み失敗を表示し、再試行でき、別の銘柄には切り替えません。
  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: '上海証券取引所' }]

  // 任意:銘柄があるプラットフォーム。2 つ以上あると、検索ウィンドウの左側にプラットフォームが並び、その 1 つだけを検索できます。
  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 は検索結果の 2 行目です(言語ごとに { en, zh, ja, ko } で渡せます。en は必須で、渡していない言語では en を表示します)。type は市場の分類(forex、metal、energy、crypto、stock、etf、other)で、検索はこれで絞り込みます。exchange は所属するプラットフォームで、すべてのプラットフォームを検索したとき、結果にプラットフォームの名前とアイコンを表示します(アイコンはデータフィードの exchanges にある同名のプラットフォームの logo)。logos はアイコンで、資産ごとに 1 つ(FX のようなペアは 2 つで、基軸通貨が上)、それぞれ 1 つのアドレスか、順に試す複数のアドレスです。アイコンがないか、どれも読み込めないときは名前の頭文字を表示します。pricePrecision は価格の小数桁で、渡さなければ足から読み取ります。tickSize は最小の値動き(0.1 など)で、フットプリントとタイム・プライス・オポチュニティの「行ごとのティック」はこれで数えます。渡さなければ小数桁の最後の 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 分ごとに使うのはこれだけなので、約定を 1 件ずつではなく、分単位で要求し、分単位で返します:

    • リクエスト { symbol, from, to, parts, signal }:[from, to) の 1 分ごとで、from と to はどちらもちょうどの分(60000 の倍数)です。to はいちばん遅くても数秒前に終わった 1 分までです(終わってから 5 秒後に要求します。プラットフォームが約定を公開するのは少し遅れるため)。parts は合計以外に何が必要かで、'levels'(価格ごとの出来高。フットプリントと成行買い・売りで分けた価格帯別出来高で使用)と 'large'(約定代金の大きい数件。大口約定で使用)があります。合計だけでよいときは空です(VD、CVD、UDV は合計だけを使います)。合計だけのリクエストは 1 回で最大 3 日分(日足の 30 日 CVD なら 10 リクエスト)、levels か large を含むリクエストは 1 回で最大 6 時間分です。新しいものから要求し、同時に進行中のリクエストは最大 2 つです。チャートが必要としなくなると signal で中断します。

    • レスポンス { covered, tickSize, minutes }:minutes は covered の中で約定があった分で、古い順です。約定のない分は書きません。1 分ごとに { time, buy, sell, count, levels?, large? } で、time はその分の開始時刻、buy と sell は成行買いと成行売りの出来高(基軸資産で、約定の数量と同じ単位)、count は約定件数です。levels を要求されたときの levels は [価格, 買い出来高, 売り出来高, 価格, …] で、価格は安い順、各価格 1 回ずつ、tickSize のグリッド上にあります。large を要求されたときの large は、その分の約定代金(価格 × 数量)が大きい最大 32 件の [時刻, 価格, 数量, 方向, …] で、方向は 1 が成行買い、-1 が成行売りです。大きい順で、同じ大きさなら早いものが先、1 分の約定が 32 件に満たないときは全件を返します。

    • covered は [from, to) のうち約定がそろっている区間 [[開始, 終了], …] です。すべてそろっていれば [[from, to]]、1 分もなければ [] です。プラットフォーム(またはあなたのサーバー)がある期間に約定を持っていない、あるいは取りこぼしている(そのとき受信していなかった、接続が切れた、もう保存していない)ときは、その前後で区間を分け、古い順に並べます。ある区間にまるごと入っている分だけがそろっているとみなされ、その中で書かれていない分は約定なしとみなします。どの区間にも入らない分は「約定なし」とみなし、以後問い合わせません。1 分はその約定がすべてそろっているときだけ covered に入れられます。そうしないとチャートに誤った数値が描かれます。途中で切れた数分は入れず、その前後のそろっている分はそのまま入れれば、切れた部分の足だけが「約定なし」になります。

    • tickSize は levels の価格の刻みで、銘柄の最小の値動きか、0(価格をそのまま)です。チャートは各価格を銘柄の tickSize に合わせて置く(同じ行に入るものは合算する)ので、銘柄のものと同じかそれより細かくする必要があります。

    • 取得できないときは、返した Promise を reject します。チャートは 5 秒後に再び問い合わせ、そのたびに待ち時間を倍にして最大 80 秒まで待ち、そのあいだその足は「失敗」になります。いまは返せないがいつ返せるかはわかっているとき(たとえばサーバーがまだ約定からこれらの分を計算しているとき)は、reject のエラーに 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 秒ごとに保存し(1 秒に複数あれば最後の 1 枚だけを残す)、同じ銘柄の複数のチャートは 1 つの板情報と 1 つの購読を共有し、最後のヒートマップを閉じると購読を解除します。取引所は過去の板情報を提供しないので、ヒートマップは購読を始めてからの分しかありません。購読した直後に、サーバーが保持している直近の区間(たとえば直近 2 分)を先に送れば、ページを再読み込みしても空になりません。

  • チャートは表示中の銘柄と時間足を購読し、切り替えると古いものの購読を解除します。アラートのある銘柄も購読します。「アラート」を参照してください。同じ銘柄と時間足は 1 回だけ購読し、チャートとアラートで共有します。

  • チャートは先に購読してから、最新の足を要求します(そのため subscribe() は getBars() より先に呼ばれます)。足がまだ届いていないあいだにプッシュされた約定と足はいったん保存し、足が届いたら受け取った順につなぎます。形成中の足が約定を取りこぼすことはなく、そのあいだに確定した足も最終的な値になります。約定だけをプッシュするデータフィードでは、どの約定が返した最後の足にすでに含まれているかを区別できないため、この間の数件の約定の出来高が二重に数えられることがあります。

プロチャートには取引所やほかのプラットフォームのデータフィードは付属しません。埋め込むページにはそれぞれ独自の相場データがあるので、上のインターフェースでつないでください。

↑↓ で選択 · Enter で開く · Esc で閉じる