> developers

日本語

English
简体中文

日本語

English
简体中文

Oracle v2 API ​

現在の Oracle V2 API のリファレンスです。OpenAPI の操作ページは REST を扱います。WebSocket の形式は専用ガイドを参照してください。

Oracle マーケットビュー では、リアルタイムの Kline、ticker、取引所の状態をブラウザーで確認できます。

Base URL ​

text
https://api.coinpost.ai/oracle

この URL に /v2/tickers?symbol=BTC や /v2/klines?symbol=BTC&quote=USD&interval=1m などのパスを追加します。ローカルサーバーは http://localhost:8083 を使用します。

認証 ​

CP Auth が有効な場合、oracle スコープを持つトークンを Authorization: Bearer <token> で /v2 REST と WebSocket 接続に送信します。ブラウザーでヘッダーを設定できない場合、WebSocket の token または access_token クエリを使用できます。

GET /v2/_hc と互換エンドポイントの GET /_hc は、認証なしで status、server.status、worker.status のみを返します。Bearer トークンの検証に成功すると詳細を返します。詳細には CP Auth の有効化が必要です。CP Auth が無効な場合は認証情報の有無にかかわらず概要のみを返します。有効時の不正な認証形式は 401、それ以外の検証失敗は CP Auth の HTTP ステータスとエラーコードを保持し、応答メッセージから内部情報を除きます。クエリの token ではヘルス詳細を取得できません。両方のパスは同じハンドラーと応答形式を使います。詳細のアクセス権限は実際のパスに対して検証するため、一方で許可されるトークンが他方で拒否される場合があります。稼働監視では Authorization を省略すると CP Auth の可用性や権限に依存せず公開状態を取得できます。

REST リソース ​

  • GET /v2/_hc: 全体、サーバー、ワーカーの公開ステータス。Bearer 認証後はビルド情報、API と銘柄別ティッカー・1m 足の状態、取引所ティッカーの受信時刻と気配時刻、ワーカーのハートビートも返します。取引所別ティッカーは exchange:pair:quote をキーとし、古い気配時刻だけではサービス障害になりません。
  • GET /v2/market-overview: キャッシュされた世界全体の時価総額、24 時間取引高、ビットコインの時価総額比率、Fear & Greed 指数。
  • GET /v2/assets: アセット一覧。filter は listed（既定）、enabled、disabled、all。
  • GET /v2/klines: USD または JPY の OHLCV。間隔は 1m、5m、15m、30m、1h、1d、1w、1M。
  • GET /v2/tickers: 集計価格と任意の過去 24 時間の基軸資産出来高。
  • GET /v2/source-klines: 取引所のネイティブ Kline キャッシュと、取得可能な進行中の 1m・1h・1d 足、未取得区間、補完バーの時刻。
  • GET /v2/source-tickers: 取引所市場ごとの最終価格、bid、ask、任意の 24 時間出来高。
  • GET /v2/exchanges: 取引所の有効設定と観測状態。
  • GET /v2/pairs: 取引ペアの有効設定と観測状態。exchange で絞り込みできます。
  • GET /v2/source-status: リアルタイムと履歴の共有ソース状態、履歴の隔離スコープ、クローズ済み Kline が進行しているか、および取引所ごとの要約。

市場価格と出来高は JSON 文字列、マーケット時刻は Unix ミリ秒です。Kline は [open_time_ms, open, high, low, close, volume, is_closed] の配列です。CoinGecko のみから生成した過去の Kline の出来高は 0 です。

symbol には BTC のような基軸資産を指定します。Kline、ticker、取引所 ticker の quote は JPY（既定）または USD です。

マーケットの有効設定 ​

ワーカーの起動や履歴生成の前に oracle markets sync を実行します。未登録の取引所とペアだけを無効状態で追加し、既存レコードは変更しません。検出されなかったペアも削除せず、unavailable に変更しません。--assets BTC,XRP と --exchanges gmo_coin,sbi_vc_trade で検出対象を絞れます。必要な取引所とペアは oracle exchanges enable EXCHANGE と oracle pairs enable EXCHANGE PAIR で手動で有効にしてください。list と disable コマンドでも設定を確認・変更できます。ワーカーは 30 秒ごとに設定を確認し、新しいペアが有効になった場合は市場を再検出します。購読変更中は reconfiguring となり、古い取引所 ticker は直ちに削除されます。履歴生成も同じ設定を使用します。

WebSocket ​

wss://api.coinpost.ai/oracle/v2/ws で Kline、集計 ticker、取引所 ticker、運用状態を配信します。購読とメッセージ形式はWebSocket ガイドを参照してください。

Docker で過去の Kline を補完する ​

Oracle リポジトリのルートで、config.yaml と必要な環境変数を含む .env を用意します。以下は GMO Coin の BTC_JPY ペアを有効にして、BTC の履歴を補完する例です。

実行前に、v2_assets に BTC が存在し、enabled=true と有効な coingecko_id が設定されている必要があります。新しいデータベースでは、まず oracle assets import --limit 500 でアセットを取り込み、PostgreSQL で対象アセットの enabled 列と asset.enabled JSON フィールドを両方更新して有効にします。markets sync は有効なアセットの市場だけを検出します。

履歴の補完前に履歴を書き込むワーカーを停止し、完了後に再起動してください。FX ファイルキャッシュを再利用できるよう、ワーカーと同じ /app/data ボリュームをマウントします。--network host は PostgreSQL と Redis のアドレスが localhost の Linux 環境向けです。それ以外では Docker ネットワークとサービス名を使用してください。

bash
docker build -t oracle:local .

oracle_run() {
  docker run --rm --network host \
    --env-file .env \
    -v "$PWD/config.yaml:/app/config.yaml:ro" \
    -v oracle-data:/app/data \
    oracle:local --config /app/config.yaml "$@"
}

oracle_run markets sync --assets BTC --exchanges gmo_coin
oracle_run pairs list gmo_coin
oracle_run exchanges enable gmo_coin
oracle_run pairs enable gmo_coin BTC_JPY
oracle_run klines --assets BTC

同期で追加された取引所とペアは無効状態です。両方の enable コマンドが完了してから klines を実行してください。他のアセットや取引所を使う場合は、対象アセットの市場を同期し、pairs list で実際のペアを確認して、選択した取引所とペアをそれぞれ有効にしてから、対象アセットを --assets に追加します。

通常の klines はチェックポイントから再開し、欠けた履歴を補完します。対象アセットの対応する全履歴を再生成する場合だけ --rebuild を追加します。klines fix は保存済み Kline の精度と履歴メタデータを修復しますが、欠けた取引所履歴は取得しません。

市場概況 ​

worker は市場概況を 5 分ごとに更新します。金額は USD 建ての JSON 数値で、last_updated はデータ提供元の RFC 3339 タイムスタンプです。指数が取得できていない場合、fear_greed は null です。指数の取得失敗時は前回値と元の時刻を保持します。前回値が 48 時間以内で市場概況の保存に成功した場合は正常とし、指数がない場合や 48 時間を超えた場合はヘルスを低下させます。キャッシュの初回作成前または期限切れの場合、GET /v2/market-overview は 503 を返します。キャッシュは最後の書き込み成功から 2 時間で期限切れになります。上流データが不合理な場合（24 時間出来高が時価総額の 3 倍超、時価総額変化が +90% 超、出来高変化が +1000% 超）は拒否して前回のキャッシュを保持し、拒否された更新は次の成功まで /v2/_hc 上で失敗扱いになります。