トークンの日次 DEX OHLC と VWAP(厳密な分数付き)

Data API から日次 DEX OHLC 価格と VWAP を照会し、TypeScript と Python で厳密な有理分数を処理し、過去データを効率的にバックフィルします。

What the DEX daily prices dataset is

BlockVectra の DEX データセットは、分散型取引所での取引アクティビティをインデックス化し、集計された日次価格指標を計算します。DEX 日次価格エンドポイント(getDexPrices)は、指定された日付範囲における指定トークンの日次出来高加重平均価格(VWAP)、価格指標(first_price、last_price、min_price、max_price フィールド)、および出来高指標を提供します。

このデータセットの提供状況はネットワークによって異なります。このデータセットを提供するチェーンについては、対応チェーンページを参照してください。

このエンドポイントはページネーションされません。要求された日付範囲内のすべての一致する日次行が data 内に直接返され、next_cursor は一切存在しません。日次集計ではなく詳細なスワップトランザクションをアプリケーションが必要とする場合は、GET /{chain}/dex/swaps を使用してください(Data API リファレンスを参照)。

Request parameters and limits

エンドポイントのルートは GET https://api.blockvectra.com/v1/data/{chain}/dex/prices です。すべてのリクエストにおいて、x-api-key ヘッダーに API key を指定して認証を行う必要があります。

このエンドポイントは以下のクエリパラメータを受け付けます:

ParameterLocationTypeRequiredDescription
chainpathstringYesチェーン識別子(例:robinhood_mainnet)
tokenquerystringYes20 バイトのベーストークンアドレス(0x は任意、大文字小文字不問)
quotequerystringNo特定のベース/クォートペアに限定するための任意の 20 バイトクォートトークンアドレス
fromquerydate stringYesUTC 開始日(当日含む)、YYYY-MM-DD
toquerydate stringYesUTC 終了日(当日含む)、YYYY-MM-DD。to - from は <= 90 日である必要があります

Constraints and error codes

リクエストが制約に違反した場合、API は構造化されたエラーボディ {"error":{"code","message"}} を返します:

  • HTTP 400 (bad_request):必須クエリパラメータ(token、from、to)の不足、無効な token/quote アドレス構文、無効な YYYY-MM-DD カレンダー日付、または from が to より後である場合。
  • HTTP 409 (span_exceeded):to - from が 90 日を超えている場合。
  • HTTP 404 (unknown_chain):{chain} が GET /chains にリストされているチェーンではない場合。
  • HTTP 422 (no_coverage):チェーンが dex_prices データセット機能に対応していない場合。
  • HTTP 503 (unavailable):サービスが一時的に利用不可。Retry-After ヘッダーに従って再試行してください。

Request examples

以下の例では、2026 年 9 月のベーストークンの日次 DEX 価格を照会します:

curl -s "https://api.blockvectra.com/v1/data/robinhood_mainnet/dex/prices?token=0x1Cdad396DB64BDa184d5182A97Dd9B3C62100b7D&from=2026-09-01&to=2026-09-30" \
  -H "x-api-key: $BLOCKVECTRA_API_KEY"

Detailed field reference

data 内の各エントリは、その UTC 日付におけるトークンペアの集計された日次 DEX 指標を表します:

Token and quote assets

  • day (string):YYYY-MM-DD 形式の UTC 日付。
  • token (string):先頭に 0x が付いた小文字の 16 進数表記の 20 バイトのベーストークンアドレス。
  • token_symbol (string または null):ベーストークンのシンボル。
  • token_name (string または null):ベーストークンの表示名。
  • quote_token (string):クォート資産のアドレス。すべてゼロのアドレス(0x0000000000000000000000000000000000000000)は、クォート資産としてのネイティブ ETH を表します。
  • quote_symbol (string または null):クォート資産のシンボル(quote_token が全ゼロアドレスの場合は "ETH")。
  • quote_name (string または null):クォート資産の表示名(quote_token が全ゼロアドレスの場合は "Ether")。
  • base_decimals (integer または null):ベーストークンの小数点桁数(0〜255)。
  • quote_decimals (integer または null):クォート資産の小数点桁数(quote_token が全ゼロアドレスの場合は 18)。

Volume and trade counts

  • swap_count (integer):この行のスワップ回数。
  • base_volume_raw (string):符号なし整数の 10 進数文字列(UInt256String)としての原子単位ベース出来高。
  • quote_volume_raw (string):符号なし整数の 10 進数文字列(UInt256String)としての原子単位クォート出来高。
  • base_volume (string または null):DecimalString として base_decimals でスケールされた可読なベーストークン出来高。base_decimals が不明な場合は null。
  • quote_volume (string または null):DecimalString としてクォートの小数点桁数でスケールされたクォート出来高、または null。

Price indicators and VWAP

  • vwap (string または null):DecimalString としての出来高加重平均価格、または null。
  • first_price (string または null):DecimalString としての始値指標、または null。
  • last_price (string または null):DecimalString としての終値指標、または null。
  • min_price (string または null):DecimalString としての最安値指標、または null。
  • max_price (string または null):DecimalString としての最高値指標、または null。

Exact fraction fields

  • first_price_numerator / first_price_denominator (string):この価格の元となる約定の生の整数量(UInt256String)です。分子は quote_amount_raw(クォートトークンの最小単位)、分母は base_amount_raw(ベーストークンの最小単位)です。decimals で換算した first_price の正確な分数ではありません。
  • last_price_numerator / last_price_denominator (string):この価格の元となる約定の生の整数量(UInt256String)です。分子は quote_amount_raw(クォートトークンの最小単位)、分母は base_amount_raw(ベーストークンの最小単位)です。decimals で換算した last_price の正確な分数ではありません。
  • min_price_numerator / min_price_denominator (string):この価格の元となる約定の生の整数量(UInt256String)です。分子は quote_amount_raw(クォートトークンの最小単位)、分母は base_amount_raw(ベーストークンの最小単位)です。decimals で換算した min_price の正確な分数ではありません。
  • max_price_numerator / max_price_denominator (string):この価格の元となる約定の生の整数量(UInt256String)です。分子は quote_amount_raw(クォートトークンの最小単位)、分母は base_amount_raw(ベーストークンの最小単位)です。decimals で換算した max_price の正確な分数ではありません。
  • refreshed_at (string):この行の更新タイムスタンプ(ISO-8601 UTC タイムスタンプ)。

生の比率 分子 / 分母 の単位は「クォート最小単位 / ベース最小単位」です。読みやすい価格(ベーストークン 1 枚あたりのクォートトークン数)は、生の比率 × 10^(base_decimals − quote_decimals) です。base_decimals または quote_decimals が null のとき、読みやすい価格は不明です。18 と仮定しないでください。0 は有効な decimals です。分母が 0 のときは割り算をせず、読みやすい価格を null として扱います。同じペア(decimals が同じ)の上昇・下落や相対変化は、生の比率のまま計算できます。

Envelope metadata (meta)

  • chain:チェーン識別子。
  • chain_slug:大文字の正規チェーンスラッグ。
  • chain_external_id:CAIP-2 形式のチェーン識別子。
  • as_of_block:チェーンの完全に書き込まれた最新ブロック(このデータセットによって報告され、リクエストパラメータとは照合されません)。
  • coverage:対応範囲の分類(このエンドポイントでは "full" を報告)。
  • refreshed_at:メタデータの更新タイムスタンプ。null の場合があります:null はこのデータの更新時刻が不明であり、古くなったデータとして扱う必要があることを意味します。ブロックベースのエンドポイントは常に値を返します。

Why prices use exact numerators and denominators

標準的な JSON の数値は IEEE-754 倍精度浮動小数点数に依存しており、精度の限界が存在します:

  1. 浮動小数点の切り捨てと誤差の蓄積:Float64 の値は 53 ビットの精度しか提供せず、トークン数量の除算では計算を重ねるごとに丸め誤差が蓄積します。
  2. 送信の安全性:値を 10 進数文字列(UInt256String)としてフォーマットすることで、JSON パーサーで精度を損なうことなく数値が HTTP 経由で転送されます。

価格指標に対して厳密な整数の分子と分母を提供することで、BlockVectra は浮動小数点変換を行わずに厳密な数学的計算を可能にします。

Handling exact fractions in TypeScript (BigInt)

TypeScript では、ネイティブの BigInt で浮動小数点を使わずに比率の比較と decimals による換算ができます。isPriceUp は同じペアの生の比率を比較し、rawRatioToHumanString は decimals で換算します。decimals が不明、または分母が 0 のときは null を返します。出力は displayDigits 桁で切り捨てます(四捨五入ではありません)。これは表示上の切り捨てで、トークン自体の精度とは別であり、有限の小数で正確に表せることを意味しません。

interface DexDailyPrice {
  base_decimals: number | null;
  quote_decimals: number | null;
  // Raw amounts: numerator is quote_amount_raw, denominator is base_amount_raw.
  first_price_numerator: string;
  first_price_denominator: string;
  last_price_numerator: string;
  last_price_denominator: string;
}

// 1. Raw ratios of one pair share the same decimals, so they compare directly.
// a / b > c / d  is equivalent to  a * d > c * b  (denominators must be non-zero)
export function isPriceUp(row: DexDailyPrice): boolean | null {
  const openNum = BigInt(row.first_price_numerator);
  const openDen = BigInt(row.first_price_denominator);
  const closeNum = BigInt(row.last_price_numerator);
  const closeDen = BigInt(row.last_price_denominator);
  if (openDen === 0n || closeDen === 0n) return null;

  return closeNum * openDen > openNum * closeDen;
}

// 2. Raw ratio -> human-readable price (quote tokens per base token):
//    human = numerator / denominator * 10^(baseDecimals - quoteDecimals)
// Returns null when a decimals value is null (0 is valid) or the denominator is 0.
// The result is truncated to displayDigits digits for display only.
export function rawRatioToHumanString(
  numeratorStr: string,
  denominatorStr: string,
  baseDecimals: number | null,
  quoteDecimals: number | null,
  displayDigits = 18
): string | null {
  if (baseDecimals === null || quoteDecimals === null) return null;
  let num = BigInt(numeratorStr);
  let den = BigInt(denominatorStr);
  if (den === 0n) return null;
  const shift = baseDecimals - quoteDecimals;
  if (shift >= 0) {
    num *= 10n ** BigInt(shift);
  } else {
    den *= 10n ** BigInt(-shift);
  }
  const unit = 10n ** BigInt(displayDigits);
  const scaled = (num * unit) / den;
  const intPart = scaled / unit;
  if (displayDigits === 0) return intPart.toString();
  const fracPart = (scaled % unit).toString().padStart(displayDigits, "0");

  return `${intPart}.${fracPart}`;
}

Handling exact fractions in Python

Python の標準ライブラリでは、正確な有理数演算に fractions.Fraction を使います。human_price は decimals による換算を正確に行い、decimals が不明、または分母が 0 のときは None を返します。format_fraction は表示用で、整数演算により偶数丸め(最近接偶数への丸め)で指定桁に丸めます。

from fractions import Fraction


def raw_ratio(numerator, denominator):
    """Raw ratio: quote atomic units per base atomic unit. None when the denominator is 0."""
    den = int(denominator)
    if den == 0:
        return None
    return Fraction(int(numerator), den)


def human_price(numerator, denominator, base_decimals, quote_decimals):
    """Quote tokens per base token = raw ratio * 10^(base_decimals - quote_decimals).

    Returns None when a decimals value is None (0 is valid) or the denominator is 0.
    """
    if base_decimals is None or quote_decimals is None:
        return None
    raw = raw_ratio(numerator, denominator)
    if raw is None:
        return None
    return raw * Fraction(10) ** (base_decimals - quote_decimals)


def percentage_change(row):
    """Same pair, same decimals: raw ratios compare directly. Exact Fraction, no float."""
    open_raw = raw_ratio(row["first_price_numerator"], row["first_price_denominator"])
    close_raw = raw_ratio(row["last_price_numerator"], row["last_price_denominator"])
    if open_raw is None or close_raw is None or open_raw == 0:
        return None
    return (close_raw - open_raw) / open_raw * 100


def format_fraction(value, digits=18):
    """Display only: round half to even at `digits` places with exact integer arithmetic."""
    quotient, remainder = divmod(abs(value.numerator) * 10**digits, value.denominator)
    twice = remainder * 2
    if twice > value.denominator or (twice == value.denominator and quotient % 2 == 1):
        quotient += 1
    whole, fraction = divmod(quotient, 10**digits)
    text = str(whole) if digits == 0 else f"{whole}.{fraction:0{digits}d}"
    return f"-{text}" if value < 0 and quotient != 0 else text

Backfilling one year of daily prices

90 日間の期間制限内で 1 年分のデータ(365 日)をバックフィルするには、日付範囲全体を最大 90 日間の連続したウィンドウに分割し、チャンク化されたリクエストを発行します:

interface DateSpan {
  from: string;
  to: string;
}

/**
 * Split a large date range into consecutive spans of at most maxDays (default: 90)
 */
export function splitDateRange(startDateStr: string, endDateStr: string, maxDays = 90): DateSpan[] {
  const spans: DateSpan[] = [];
  let currentStart = new Date(startDateStr);
  const end = new Date(endDateStr);

  while (currentStart <= end) {
    const chunkEnd = new Date(currentStart);
    chunkEnd.setUTCDate(chunkEnd.getUTCDate() + (maxDays - 1));
    const effectiveEnd = chunkEnd < end ? chunkEnd : end;

    spans.push({
      from: currentStart.toISOString().slice(0, 10),
      to: effectiveEnd.toISOString().slice(0, 10),
    });

    const nextStart = new Date(effectiveEnd);
    nextStart.setUTCDate(nextStart.getUTCDate() + 1);
    currentStart = nextStart;
  }

  return spans;
}

/**
 * Backfill token daily prices across multiple 90-day chunks
 */
export async function backfillTokenDailyPrices(
  chain: string,
  token: string,
  startDate: string,
  endDate: string,
  apiKey: string
) {
  const chunks = splitDateRange(startDate, endDate, 90);
  const allDailyPrices = [];

  for (const chunk of chunks) {
    const url = new URL(`https://api.blockvectra.com/v1/data/${chain}/dex/prices`);
    url.searchParams.set("token", token);
    url.searchParams.set("from", chunk.from);
    url.searchParams.set("to", chunk.to);

    const res = await fetch(url, {
      headers: { "x-api-key": apiKey },
    });

    if (!res.ok) {
      throw new Error(`Failed to fetch span ${chunk.from}..${chunk.to}: HTTP ${res.status}`);
    }

    const json = await res.json();
    allDailyPrices.push(...json.data);
  }

  return allDailyPrices;
}

Capacity and CU usage calculations

Data API のすべてのエンドポイントは、消費量を Compute Units(CU)単位で計測します。data.dex_prices のコールあたりの CU 重み付けと、トークンバックフィルの推定消費量は以下のように計算されます:

メソッドの重み付けdata.dex_prices: 15 CU / call
  • 200 トークンの 1 年分の日次価格をバックフィル: リクエストあたりの最大範囲は 90 日であり、365 日分をカバーするにはトークンあたり 5 チャンク、合計 1,000 回の呼び出しが必要です。 総消費量は 15,000 CU(無料プランのサイクル枠の約 <0.1%)、定価換算で約 <$0.01。
  • 日常のメンテナンス(毎日 200 トークンを 1 回更新): 200 コール/日(3,000 CU/日)、30 日のサイクルあたり約 6,000 コール(90,000 CU、無料枠の約 0.3%)、定価換算で月額約 <$0.01。

バックフィル量を拡張する場合や、より高いリクエスト同時実行数が必要な場合は、コンソールの請求ページでオンチェーンチャージを行い、有料アカウントにアップグレードしてください。有効な料金レートとユニット換算については、料金ページを参照してください。

Next steps

最終更新:

このページの目次