FX APIから返されるデータはどう読み取る？価格・タイムスタンプ・取引銘柄を解説

FX APIを接続すると、開発者は通常、取引銘柄、価格、時刻情報などを含むJSONデータを受け取ります。APIによっては、売買板の情報や、それぞれの価格に対応する数量フィールドも返されます。各フィールドの意味を理解していないと、BidをAskとして扱ったり、ミリ秒単位のタイムスタンプを秒単位として処理したり、異なる通貨ペアの価格を誤ったチャートに表示したりする可能性があります。

FX市場データを正しく理解するには、価格だけでなく、取引銘柄、価格の時刻、板の数量も合わせて確認する必要があります。ここでは、AllTickのFX板情報を例に、これらのデータをどのように読み取り、処理すればよいかを解説します。

FX APIから返される価格とvolumeの見方

FXの価格は通常、EURUSD、GBPUSD、USDJPYなどの通貨ペアで表されます。EURUSDを例にすると、EURは基軸通貨、USDは決済通貨であり、1ユーロに対して何米ドルになるかを示します。

AllTickの板データでは、bidsとasksがそれぞれ買い板と売り板を表し、各価格レベルにはpriceとvolumeの2つのフィールドが含まれます。

以下はEURUSDのサンプルデータです。数値はフィールド構造を説明するためのものであり、リアルタイムAPIから取得した実際のデータではありません。

{
  "ret": 200,
  "msg": "ok",
  "trace": "demo-trace",
  "data": {
    "tick_list": [
      {
        "code": "EURUSD",
        "seq": "123456",
        "tick_time": "1793260800000",
        "bids": [
          {
            "price": "1.08518",
            "volume": "120000"
          }
        ],
        "asks": [
          {
            "price": "1.08522",
            "volume": "95000"
          }
        ]
      }
    ]
  }
}

主なフィールドの意味は次のとおりです。

Bidは基軸通貨の買い気配、Askは基軸通貨の売り気配を表します。取引する側の視点では、基軸通貨を売る場合は通常Bidを参照し、買う場合はAskを参照します。

例えば、上記のEURUSDでは、Bidが1.08518、Askが1.08522です。この2つの価格の差がスプレッド（Spread）です。

Spread = Ask − Bid

計算結果は0.00004です。EURUSDでは通常、1 pipは0.0001に相当するため、このスプレッドは0.4 pipとなります。

volumeは、対応する板の価格レベルにおける数量を示します。これは通貨ペアの累計取引量ではなく、ローソク足の出来高と同じものでもありません。数量の単位については、対象となる製品のデータ定義を確認する必要があります。すべての資産で同じ単位が使用されていると決めつけないようにしてください。

現在のAllTickのデータ仕様では、FX、貴金属、エネルギー、株式、暗号資産のデータにvolumeが含まれます。一方、一部のCFD指数ではこのフィールドが提供されません。そのため、複数市場のデータを処理する場合は、銘柄ごとにフィールド構造が異なる可能性を考慮し、すべての製品でvolumeが必須であると仮定しないことが重要です。

タイムスタンプを正しく変換して気配値の時刻を表示する方法

価格は気配値の水準を示し、タイムスタンプはその気配値がいつのものかを判断するために使用します。また、気配値が適切なタイミングで更新されているかを確認する際にも役立ちます。

AllTickでは、インターフェースによって時間フィールドの形式が異なります。例えば、HTTP板情報データのtick_timeはミリ秒単位のタイムスタンプを使用し、K線データのtimestampは秒単位のタイムスタンプを使用します。

ミリ秒単位のタイムスタンプを秒単位としてそのまま変換関数に渡すと、正しくない日時が表示されます。

板情報の時刻は、Pythonで次のように変換できます。

from datetime import datetime, timezone

tick_time = "1793260800000"

quote_time = datetime.fromtimestamp(
    int(tick_time) / 1000,
    tz=timezone.utc
)

print(quote_time.isoformat())

まず文字列を整数に変換し、1000で割って秒単位にします。その後、UTCタイムゾーンを指定します。

K線データを処理する場合は、秒単位のタイムスタンプとして変換します。

timestamp = "1793260800"

kline_time = datetime.fromtimestamp(
    int(timestamp),
    tz=timezone.utc
)

print(kline_time.isoformat())

実際の開発では、数値の桁数だけで、すべてのAPIの時間単位を判断しないでください。まず対象インターフェースのフィールド定義を確認することが重要です。

また、マーケットデータの遅延を判断する場合は、ローカルでデータを受信した時刻も記録し、サーバー間の時計が同期されているかを考慮する必要があります。ローカルの時刻誤差をネットワーク遅延と誤認しないようにしてください。

取引銘柄コードを正しい相場データに対応させる方法

取引銘柄フィールドは、それぞれの気配値がどの市場商品に属するかを識別するために使用します。AllTickのFX銘柄コードは、EURUSD、GBPUSD、USDJPYのような6文字の通貨コード形式を採用しています。

USDJPYを例にすると、USDが基軸通貨、JPYが決済通貨であり、1米ドルに対して何円になるかを示します。

開発時には、APIから返された元のcodeを保持し、画面表示用の形式は別途管理することをおすすめします。例えば、APIではEURUSDを使用し、フロントエンドではEUR/USDと表示できます。ただし、表示形式をそのままAPIのリクエストパラメータに置き換えないようにしてください。

システムで複数の通貨ペアを同時に購読する場合は、code、価格、volume、timestampを同じマーケットデータレコードに保存することをおすすめします。これにより、非同期更新時に価格と取引銘柄が一致しなくなる問題を防ぎやすくなります。

PythonでFX板データを解析する

フィールドの意味を理解したら、バックエンドでデータ解析を一元化できます。以下では、AllTick HTTP Interface APIの/depth-tick板情報インターフェースを例に、EURUSDのBid、Ask、数量、時刻を取得する方法を示します。

import json
import requests
from decimal import Decimal
from datetime import datetime, timezone

TOKEN = "YOUR_TOKEN_HERE"

query = {
    "trace": "fx_depth_demo",
    "data": {
        "symbol_list": [{"code": "EURUSD"}]
    }
}

response = requests.get(
    "https://quote.alltick.co/quote-b-api/depth-tick",
    params={
        "token": TOKEN,
        "query": json.dumps(query, separators=(",", ":"))
    },
    timeout=10
)

response.raise_for_status()
result = response.json()

if result.get("ret") != 200:
    raise RuntimeError(f"API error: {result}")

tick_list = result.get("data", {}).get("tick_list", [])

for item in tick_list:
    bids = item.get("bids") or []
    asks = item.get("asks") or []

    if not bids or not asks:
        continue

    bid = bids[0]
    ask = asks[0]

    bid_price = Decimal(bid["price"])
    ask_price = Decimal(ask["price"])

    bid_volume = bid.get("volume")
    ask_volume = ask.get("volume")

    quote_time = datetime.fromtimestamp(
        int(item["tick_time"]) / 1000,
        tz=timezone.utc
    )

    print({
        "symbol": item["code"],
        "bid": str(bid_price),
        "bid_volume": bid_volume,
        "ask": str(ask_price),
        "ask_volume": ask_volume,
        "spread": str(ask_price - bid_price),
        "time": quote_time.isoformat()
    })

このコードでは、APIリクエスト、レスポンスステータスの確認、買い売り気配値の解析、板数量の取得、タイムスタンプの変換を行います。価格の計算にはDecimalを使用しており、通常の浮動小数点演算による精度の問題を軽減できます。

このサンプルは、板情報に対応するEURUSDを対象にしています。一部のCFD指数のようにvolumeを提供しない銘柄については、このフィールドを任意項目として扱う必要があります。また、ある銘柄の板データが取得できない場合も、すぐに価格異常と判断せず、その銘柄が板情報に対応しているか、現在の相場状態に問題がないかを先に確認してください。

FXのデータニーズに応じて適切なAPIを選ぶ

アプリケーションで現在のBidとAskだけを取得したい場合は、HTTP板情報クエリインターフェースを使用できます。板情報の変化を継続的に受信したい場合は、WebSocketによる購読を利用できます。約定データや過去のK線を取得する場合は、それぞれに対応するデータインターフェースを選択してください。

また、異なる種類のマーケットデータに含まれるvolumeは区別する必要があります。

• 板情報のvolume：BidまたはAskの各価格レベルに対応する数量。
• 逐次約定データのvolume：個々の約定記録に対応する数量。
• K線データのvolume：該当するK線期間内の取引量。

これらは同じフィールド名を使用していても、業務上の意味は異なります。混同して計算しないようにしてください。

AllTickはFXマーケットデータAPIを提供しており、EURUSD、GBPUSD、USDJPYなどの通貨ペアに対応しています。また、RESTとWebSocketを通じて、異なる形式のマーケットデータを利用できます。開発者は、相場画面の表示、リアルタイム購読、過去データ分析などの用途に応じて、適切なインターフェースを選択できます。

本番環境に接続する前に、取引銘柄コード、価格フィールド、タイムスタンプの単位、および現在のデータタイプでvolumeが提供されるかを確認してください。AllTick公式サイトから、製品情報や開発者向けリソースを確認できます。

FXマーケットデータシステムでは、価格を正しく読み取ることは基本にすぎません。価格、時間、取引銘柄、板数量を正確に理解してこそ、その後のキャッシュ処理、相場表示、取引戦略の計算を信頼できるデータ構造に基づいて行うことができます。