piff

Dart client SDK for the PIFF protocol — Protocol for Interactive Financial Feeds.

PIFF is a WebSocket-based protocol for real-time financial market data distribution and trading operations. This package provides a complete Dart client implementation with idiomatic APIs, strong typing, and comprehensive test coverage.

Features

• 📡 Real-time market data — subscribe to live quotes for futures, options, and equities
• 📊 K-line / Tick series — request historical and streaming chart data with sliding windows
• 🏦 Trading operations — login, insert orders, cancel orders via TradeSession
• 🔐 JWT authentication — TqAuth handles token refresh and MD URL discovery
• 🔄 Auto-reconnect — WebSocket reconnection handled transparently
• 🧩 Incremental updates — DataManager merges incremental JSON patches from the server
• 🧪 Testable by design — DI via ClientTestOverrides, interfaces for WebSocket and DataManager

Installation

dependencies:
  piff: ^0.1.0

Quick Start

import 'package:piff/piff.dart';

// 1. Authenticate
final auth = TqAuth(userName: 'your_username', password: 'your_password');
await auth.login();

// 2. Create a client
final client = Client(
  auth: auth,
  config: DefaultClientConfig(
    username: 'your_username',
    password: 'your_password',
  ),
);

// 3. Initialize market data
await client.initMarket();

// 4. Subscribe to real-time quotes
final sub = client.subscribeQuote(['SHFE.au2312', 'DCE.m2401']);

// 5. Listen for updates
sub.onQuoteUpdate.listen((quotes) {
  for (final quote in quotes) {
    print('${quote.instrumentId}: ${quote.lastPrice}');
  }
});

// 6. Log in to a trading account (simulated broker)
final session = client.loginTrade('sim', 'trader01', 'password');

// 7. Insert an order
await session.insertOrder(InsertOrderRequest()
  ..symbol = 'SHFE.au2312'
  ..direction = Direction.buy
  ..offset = Offset.open
  ..priceType = PriceType.limit
  ..limitPrice = 450.0
  ..volume = 1,
);

// 8. Clean up
client.close();

Key Concepts

Client

Client is the main entry point. It manages the lifecycle of the market data WebSocket, quote subscriptions, and multiple concurrent trade sessions.

final client = Client(auth: auth, config: config);
await client.initMarket();

QuoteSubscription

Subscribe to real-time tick data for one or more instruments. The subscription accumulates symbols — each call to subscribeQuote adds to the existing subscription.

final sub = client.subscribeQuote(['SHFE.au2312']);
sub.addSymbols(['DCE.m2401']); // add more later

sub.getQuote('SHFE.au2312'); // returns Quote?

Series (K-line / Tick)

final seriesApi = client.series()!;
final series = await seriesApi.getKlineSeries(SeriesOptions()
  ..symbols = ['SHFE.au2312']
  ..duration = Duration(minutes: 1)
  ..viewWidth = 200,
);

series.onUpdate.listen((data) {
  final klines = data.single!.data;
  print('Latest close: ${klines.last.close}');
});

TradeSession

Each TradeSession represents a logged-in trading account connection.

final session = client.loginTrade('broker_id', 'user_id', 'password');

// Account info
final account = session.getAccount();

// Positions
final positions = session.getPositions();

// Orders
final orders = session.getOrders();

DataManager

DataManager handles incremental JSON merging from the server. You generally don't interact with it directly, but it's injectable for testing.

Data Structures

Class	Description
Quote	Real-time tick data for an instrument
Kline	Single K-line (OHLCV + open interest)
Tick	Single tick with full order book snapshot
Account	Trading account balance and margin summary
Position	Position for a single instrument
Order	Order record with status
Trade	Execution / fill record

Protocol

PIFF is documented in the protocol RFC draft. The Go reference implementation lives at piff-go/client.

License

MIT