本文へ移動
QuantLabTickDirect

ドキュメントリソース

Python サンプル

認証から受信までを 1 ファイルで行う、接続を確かめるためのサンプルです。

APIキーでの認証、購読、Heartbeat、ティックの読み取りまでを、1 つのファイル(freqrelay_client.py)で行います。

freqrelay_client.py をダウンロード

必要なもの

  • Python 3.10 以降
  • PyJWT(Ed25519 の署名に cryptography を使います)
  • ggguilds の契約画面で発行した APIキーの、キー ID(ggg_...)と秘密鍵(PEM ファイル)
pip install "pyjwt[crypto]"

使い方

python freqrelay_client.py --server tokyo-alpha-1.tick.quantlab.fi:17000 \
  --key-id ggg_xxxxxxxx --key-file ggguilds-api-key.pem \
  --symbols EURUSD,USDJPY
Authenticated
Subscribed to 2 symbols: EURUSD, USDJPY
EURUSD bid=1.08529 ask=1.08540 upstream=09:41:08.108Z
USDJPY bid=151.01200 ask=151.02500 upstream=09:41:08.112Z
...
datagrams=992 ticks=1041 lost=0 delivery-latency p50=65us p99=140us
オプション意味
--serverTick サーバーの host:port
--key-idAPIキーのキー ID
--key-fileAPIキーの秘密鍵(PKCS#8 の PEM)
--symbols購読するシンボル(カンマ区切り、64 個まで)。既定は EURUSD,USDJPY
--duration受け取る秒数。0(既定)なら Ctrl+C まで
--quietティックを 1 件ずつ表示せず、5 秒ごとの集計だけを表示する
  • 5 秒ごとに、受け取ったデータグラムとティックの数、連番の抜けから数えた欠損(lost)、届くまでの時間(delivery-latency)を表示します。届くまでの時間は、Tick サーバーがティックを受け取った時刻から、このプログラムが受け取るまでの時間で、2 台の時計のずれを含みます。
  • 価格は小数 5 桁に丸めて表示します。
  • Ctrl+C で止めると、空の Subscribe を送って購読を終わらせます。IP アドレスの枠がすぐに空きます。

うまくいかないとき

認証が拒否されると、理由を表示します(意味は結果と終了理由)。

  • UnknownKey: APIキーを発行した直後なら、1 分ほど待ってください。サンプルは 10 秒ごとに再試行します。
  • InvalidSignature: キー ID と秘密鍵の組み合わせが合っていません。
  • TokenExpired: このマシンの時計がずれています。NTP で合わせてください。
  • IpLimitReached: プランの IP アドレスの上限に達しています。ほかの IP アドレスでの接続をやめると、すぐに(止め方によっては 5 秒後に)接続できます。
  • 何も表示されない: ファイアウォールが UDP を通していないか、ホスト名やポートが違います。

自分のプログラムに組み込むとき

  • 認証から受信まで、1 つの UDP ソケットを使い続けてください。
  • Heartbeat を 1 秒ごとに送り、HeartbeatAck で購読が終わったと知らされたら、Hello からやり直してください。
  • Python は 1 件ずつの処理が遅いので、全シンボルを低遅延で処理するときは、受信のスレッドを分けるか、ほかの言語で実装してください。

ソース

freqrelay_client.py を表示
#!/usr/bin/env python3
"""QuantLab TickDirect の Tick サーバーに接続して、ティックを表示するサンプル。

接続を確かめるための最小の実装です。仕様は https://quantlab.fi/docs を参照してください。

    pip install "pyjwt[crypto]"
    python freqrelay_client.py --server tokyo-alpha-1.tick.quantlab.fi:17000 \\
        --key-id ggg_... --key-file ggguilds-api-key.pem --symbols EURUSD,USDJPY

Ctrl+C で止めると、空の Subscribe を送って購読を終わらせます(IP 上限の枠がすぐに空きます)。
"""

from __future__ import annotations

import argparse
import base64
import socket
import struct
import sys
import time
from dataclasses import dataclass, field

import jwt  # PyJWT

# ---- SBE(freqrelay-sbe.xml、スキーマ ID 1、version 1)。すべてリトルエンディアン ----

SCHEMA_ID = 1
SCHEMA_VERSION = 1

SUBSCRIBE = 1
SUBSCRIBE_ACK = 2
HEARTBEAT = 3
HEARTBEAT_ACK = 4
TICKS = 5
HELLO = 6
CHALLENGE = 7
AUTHENTICATE = 8
AUTHENTICATE_ACK = 9

HEADER = struct.Struct("<HHHH")  # blockLength, templateId, schemaId, version
GROUP = struct.Struct("<HH")  # blockLength, numInGroup
TICK = struct.Struct("<Hqqqq")  # symbolId, bid, ask, upstreamTime, receiveTime

PRICE_SCALE = 100_000_000  # 価格は × 10^8 の固定小数点
NULL_SYMBOL_ID = 0xFFFF
MAX_DATAGRAM = 1200

AUTHENTICATE_RESULTS = [
    "Accepted", "InvalidCookie", "MalformedToken", "InvalidSignature", "TokenExpired", "AudienceMismatch",
    "UnknownKey", "KeyRevoked", "KeyExpired", "PlanNotAccepted", "IpLimitReached", "EndpointLimitReached",
    "ServerFull", "RateLimited", "NotReady",
]
END_REASONS = ["None", "Unknown", "HeartbeatTimeout", "Unsubscribed", "KeyRevoked", "KeyExpired", "Replaced"]
UPSTREAM_STATUSES = ["Disconnected", "Connecting", "Connected"]

# 再試行しても直らない拒否。設定を見直す必要がある
FATAL_RESULTS = {"MalformedToken", "InvalidSignature", "AudienceMismatch", "KeyRevoked", "KeyExpired", "PlanNotAccepted"}


def header(template_id: int, block_length: int) -> bytes:
    return HEADER.pack(block_length, template_id, SCHEMA_ID, SCHEMA_VERSION)


def encode_hello() -> bytes:
    # 32 バイトの 0 の詰め物。サーバーは、Challenge より小さい Hello には応えない
    return header(HELLO, 32) + bytes(32)


def encode_authenticate(request_id: int, token: str) -> bytes:
    data = token.encode("ascii")
    return header(AUTHENTICATE, 4) + struct.pack("<IH", request_id, len(data)) + data


def encode_subscribe(subscriber_token: bytes, request_id: int, symbols: list[str]) -> bytes:
    names = b"".join(symbol.encode("utf-8").ljust(16, b"\0")[:16] for symbol in symbols)
    return header(SUBSCRIBE, 20) + subscriber_token + struct.pack("<I", request_id) + GROUP.pack(16, len(symbols)) + names


def encode_heartbeat(subscriber_token: bytes) -> bytes:
    return header(HEARTBEAT, 16) + subscriber_token


def read_symbol_name(field_bytes: bytes) -> str:
    return field_bytes.split(b"\0", 1)[0].decode("utf-8", errors="replace")


def make_jwt(key_id: str, private_key: bytes, audience: str, cookie: bytes) -> str:
    """ggguilds の標準の JWT に、Challenge の cookie を nonce として足したもの。"""
    now = int(time.time())
    return jwt.encode(
        {
            "iss": key_id,
            "aud": audience,
            "iat": now,
            "exp": now + 300,
            "nonce": base64.urlsafe_b64encode(cookie).rstrip(b"=").decode("ascii"),
        },
        private_key,
        algorithm="EdDSA",
    )


# ---- クライアント ----


@dataclass
class Stats:
    datagrams: int = 0
    ticks: int = 0
    lost: int = 0
    expected_sequence: int = 1
    latencies_us: list[float] = field(default_factory=list)


class Client:
    RETRY_SECONDS = 1.0
    HEARTBEAT_SECONDS = 1.0

    def __init__(self, server: tuple[str, int], key_id: str, private_key: bytes, audience: str, symbols: list[str], quiet: bool):
        self.server = server
        self.key_id = key_id
        self.private_key = private_key
        self.audience = audience
        self.symbols = symbols
        self.quiet = quiet
        # 認証から受信まで、1 つのソケット(送信元のポート)を使い続ける
        self.sock = socket.socket(socket.AF_INET, socket.SOCK_DGRAM)
        self.sock.setsockopt(socket.SOL_SOCKET, socket.SO_RCVBUF, 4 << 20)
        self.sock.connect(server)
        self.request_id = 0
        self.subscriber_token: bytes | None = None
        self.symbol_names: dict[int, str] = {}
        self.stats = Stats()

    def send(self, message: bytes) -> None:
        self.sock.send(message)

    def receive(self, timeout: float) -> tuple[int, memoryview, memoryview] | None:
        """1 つ受け取る。(templateId, ルートブロック, ルートブロックの後ろ) を返す。"""
        # settimeout(0) はソケットを待たないモードにして、データが無いと BlockingIOError になる。0 以下は短い待ちにそろえる
        self.sock.settimeout(max(timeout, 0.001))
        try:
            data = memoryview(self.sock.recv(65536))
        except (socket.timeout, BlockingIOError):
            return None
        except ConnectionRefusedError:
            # Tick サーバーのポートが閉じている(再起動中など)。ICMP の到達不能で recv がすぐ失敗するので、
            # 応答がなかったときと同じだけ待ってから返す(すぐ送り直して要求を連発しないため)
            time.sleep(max(timeout, 0.0))
            return None
        if len(data) < HEADER.size:
            return None
        block_length, template_id, schema_id, _ = HEADER.unpack_from(data)
        if schema_id != SCHEMA_ID or len(data) < HEADER.size + block_length:
            return None
        root = data[HEADER.size:HEADER.size + block_length]
        return template_id, root, data[HEADER.size + block_length:]

    def wait_for(self, template_id: int, timeout: float) -> tuple[memoryview, memoryview] | None:
        """指定した種類のメッセージを待つ。その間に届いた Ticks は処理する。"""
        deadline = time.monotonic() + timeout
        while (remaining := deadline - time.monotonic()) > 0:
            message = self.receive(remaining)
            if message is None:
                return None
            received_id, root, rest = message
            if received_id == template_id:
                return root, rest
            if received_id == TICKS:
                self.on_ticks(root, rest)
        return None

    def connect(self) -> None:
        """Hello → Challenge → Authenticate → Subscribe。応答がなければ送り直す。"""
        while True:
            self.subscriber_token = None
            self.send(encode_hello())
            challenge = self.wait_for(CHALLENGE, self.RETRY_SECONDS)
            if challenge is None:
                continue
            cookie = bytes(challenge[0][:16])

            self.request_id += 1
            self.send(encode_authenticate(self.request_id, make_jwt(self.key_id, self.private_key, self.audience, cookie)))
            ack = self.wait_for(AUTHENTICATE_ACK, self.RETRY_SECONDS)
            if ack is None:
                continue
            _, result = struct.unpack_from("<IB", ack[0])
            result_name = AUTHENTICATE_RESULTS[result] if result < len(AUTHENTICATE_RESULTS) else str(result)
            if result_name != "Accepted":
                if result_name in FATAL_RESULTS:
                    raise SystemExit(f"Authentication failed: {result_name} (see https://quantlab.fi/docs/codes)")
                print(f"Authentication rejected: {result_name}; retrying", file=sys.stderr)
                time.sleep(2 if result_name != "UnknownKey" else 10)
                continue
            self.subscriber_token = bytes(ack[0][5:21])
            print("Authenticated", file=sys.stderr)

            if self.subscribe():
                return

    def subscribe(self) -> bool:
        for _ in range(5):
            self.request_id += 1
            self.send(encode_subscribe(self.subscriber_token, self.request_id, self.symbols))
            ack = self.wait_for(SUBSCRIBE_ACK, self.RETRY_SECONDS)
            if ack is None:
                continue
            root, rest = ack
            _, result = struct.unpack_from("<IB", root)
            if result != 0:
                print("Subscribe rejected: UnknownSubscriber; authenticating again", file=sys.stderr)
                return False
            entry_length, count = GROUP.unpack_from(rest)
            for i in range(count):
                offset = GROUP.size + i * entry_length
                (symbol_id,) = struct.unpack_from("<H", rest, offset)
                name = read_symbol_name(bytes(rest[offset + 2:offset + 18]))
                if symbol_id == NULL_SYMBOL_ID:
                    print(f"Unknown symbol: {name}", file=sys.stderr)
                else:
                    self.symbol_names[symbol_id] = name
            print(f"Subscribed to {len(self.symbol_names)} symbols: {', '.join(self.symbol_names.values())}", file=sys.stderr)
            return True
        return False

    def on_ticks(self, root: memoryview, rest: memoryview) -> None:
        (sequence,) = struct.unpack_from("<Q", root)
        stats = self.stats
        if sequence > stats.expected_sequence:
            stats.lost += sequence - stats.expected_sequence
        if sequence >= stats.expected_sequence or sequence == 1:
            stats.expected_sequence = sequence + 1
        stats.datagrams += 1

        now_ns = time.time_ns()
        entry_length, count = GROUP.unpack_from(rest)
        for i in range(count):
            symbol_id, bid, ask, upstream_ns, receive_ns = TICK.unpack_from(rest, GROUP.size + i * entry_length)
            stats.ticks += 1
            # 到達遅延(サーバーの受信時刻から、ここで受け取るまで。2 台の時計のずれを含む)
            stats.latencies_us.append((now_ns - receive_ns) / 1000)
            if not self.quiet:
                upstream = time.strftime("%H:%M:%S", time.gmtime(upstream_ns / 1e9)) + f".{upstream_ns % 1_000_000_000 // 1_000_000:03d}"
                print(f"{self.symbol_names.get(symbol_id, symbol_id)} bid={bid / PRICE_SCALE:.5f} ask={ask / PRICE_SCALE:.5f} upstream={upstream}Z")

    def run(self, duration: float) -> None:
        self.connect()
        end = time.monotonic() + duration if duration > 0 else float("inf")
        next_heartbeat = time.monotonic()
        next_report = time.monotonic() + 5
        while time.monotonic() < end:
            now = time.monotonic()
            if now >= next_heartbeat:
                self.send(encode_heartbeat(self.subscriber_token))
                next_heartbeat = now + self.HEARTBEAT_SECONDS
            if now >= next_report:
                self.report()
                next_report = now + 5

            message = self.receive(max(0.0, min(next_heartbeat, next_report) - time.monotonic()))
            if message is None:
                continue
            template_id, root, rest = message
            if template_id == TICKS:
                self.on_ticks(root, rest)
            elif template_id == HEARTBEAT_ACK:
                subscribed, upstream, reason = struct.unpack_from("<BBB", root)
                if not subscribed:
                    print(f"Subscription ended: {END_REASONS[reason] if reason < len(END_REASONS) else reason}; connecting again", file=sys.stderr)
                    self.connect()
                elif upstream != 2:
                    print(f"Upstream LP: {UPSTREAM_STATUSES[upstream] if upstream < len(UPSTREAM_STATUSES) else upstream}", file=sys.stderr)

    def report(self) -> None:
        stats = self.stats
        latencies = sorted(stats.latencies_us)
        p50 = latencies[len(latencies) // 2] if latencies else 0.0
        p99 = latencies[min(len(latencies) - 1, len(latencies) * 99 // 100)] if latencies else 0.0
        print(f"datagrams={stats.datagrams} ticks={stats.ticks} lost={stats.lost} delivery-latency p50={p50:.0f}us p99={p99:.0f}us", file=sys.stderr)
        stats.latencies_us.clear()

    def close(self) -> None:
        if self.subscriber_token is not None:
            # 空の Subscribe で購読を終わらせ、IP 上限の枠をすぐに空ける
            self.request_id += 1
            self.send(encode_subscribe(self.subscriber_token, self.request_id, []))
        self.sock.close()


def main() -> None:
    parser = argparse.ArgumentParser(description="FreqRelay のティックを受け取って表示する")
    parser.add_argument("--server", required=True, help="Tick サーバーのアドレスとポート(host:port)")
    parser.add_argument("--key-id", required=True, help="APIキーのキー ID(ggg_...)")
    parser.add_argument("--key-file", required=True, help="APIキーの秘密鍵(PKCS#8 の PEM)")
    parser.add_argument("--symbols", default="EURUSD,USDJPY", help="購読するシンボル(カンマ区切り、64 個まで)")
    parser.add_argument("--audience", default="freqrelay", help="JWT の aud")
    parser.add_argument("--duration", type=float, default=0, help="受け取る秒数(0 なら Ctrl+C まで)")
    parser.add_argument("--quiet", action="store_true", help="ティックを 1 件ずつ表示しない(5 秒ごとの集計だけ)")
    args = parser.parse_args()

    host, _, port = args.server.rpartition(":")
    with open(args.key_file, "rb") as f:
        private_key = f.read()
    symbols = [symbol.strip() for symbol in args.symbols.split(",") if symbol.strip()]

    client = Client((socket.gethostbyname(host), int(port)), args.key_id, private_key, args.audience, symbols, args.quiet)
    try:
        client.run(args.duration)
    except KeyboardInterrupt:
        pass
    finally:
        client.report()
        client.close()


if __name__ == "__main__":
    main()