caishen

PDS - Price Data Services

RISE Framework Specification

Spec ID: 03
Version: 1.0
Document ID: caishen-rise-pds-v1.0
Last Updated: 2025-01-31

Creative Intent

What PDS Enables Users to Create:

Unified price history access across multiple data sources
Real-time and historical OHLCV data retrieval
Multi-timeframe price synchronization
Price data normalization for analysis

Desired Outcomes:

Users receive consistent price data regardless of source
Historical data is accessible for any supported timeframe
Price updates trigger downstream analysis workflows
Data is cached and persisted for performance

Core Components

PDSService

The primary service interface for price data operations.

Behavior:

Fetches price history from configured data source
Normalizes data to standard PriceHistoryBase format
Manages price data caching
Publishes price update notifications

PDSPHistoryServices

Historical price data provider.

Behavior:

Retrieves historical bars for instrument/timeframe/date range
Converts raw data to PriceHistoryBase objects
Supports date range queries
Handles missing data gracefully

PDSEngine

Console application for batch price updates.

Behavior:

Command-line interface for price data refresh
Supports multiple instruments (comma-separated)
Configurable timeframe and date range
Writes output to JSON/CSV files

Service Contracts

IPDSService

Interface IPDSService:

  Method GetPriceHistory:
    Input:
      - instrument: string
      - timeframe: string
      - nbBars: int
      - dtEnd: string (optional, default "now")
    Output: PriceHistoryBase
    Behavior: Returns OHLCV bars for specified range

  Method GetPriceHistoryRange:
    Input:
      - instrument: string
      - timeframe: string
      - dtStart: string
      - dtEnd: string
    Output: PriceHistoryBase
    Behavior: Returns all bars within date range

  Method GetLatestQuote:
    Input:
      - instrument: string
    Output: QuoteBase
    Behavior: Returns most recent bid/ask quote

  Method RefreshPrices:
    Input:
      - instruments: string (comma-separated)
      - timeframe: string
    Output: RefreshPricesResponse
    Behavior: Updates price cache from source

Data Entities

PriceHistoryBase

PriceHistoryBase:
  - Instrument: string
  - Timeframe: string
  - Bars: List<PriceBar>
  - StartDate: DateTime
  - EndDate: DateTime
  - Source: string

PriceBar (Quote)

PriceBar implements IQuote:
  - Date: DateTime
  - Open: decimal
  - High: decimal
  - Low: decimal
  - Close: decimal
  - Volume: long
  - Ask: QuoteSide (optional)
  - Bid: QuoteSide (optional)

QuoteSide

QuoteSide:
  - O: decimal    # Open
  - H: decimal    # High
  - L: decimal    # Low
  - C: decimal    # Close

PovBase

PovBase:
  - Instrument: string    # "EUR/USD"
  - Timeframe: string     # "H4"
  
  Constructor: PovBase(string povString)
    # Parses "EUR-USD_H4" format
    
  Method ToString():
    Returns "{Instrument}_{Timeframe}"

PDSEngine CLI

Usage

PDSEngine2203.exe <instruments> <timeframe> <startDate> <endDate> [avg] [full]

Parameters:
  instruments  - Comma-separated instrument list or "*.pair" for currency base
  timeframe    - m5, m15, H1, H2, H3, H4, H6, H8, D1, W1, M1
  startDate    - Date string or "L" for last available
  endDate      - Date string or "L" for latest
  avg          - "avg" to calculate average of bid/ask, "noavg" for raw
  full         - "full" for complete export, "nofull" for incremental

Examples

# Update 5-minute data for EUR/USD
PDSEngine2203.exe EUR-USD m5 L L avg

# Update H4 data for all USD pairs
PDSEngine2203.exe USD.pair H4 L L avg

# Update multiple instruments
PDSEngine2203.exe "EUR-USD,GBP-USD,USD-JPY" H4 L L avg

Creative Advancement Scenarios

Scenario 1: Retrieve Price History

Creative Advancement Scenario: Get Price History for Analysis

Desired Outcome: 300 bars of EUR/USD H4 data for CDB calculation

Current Reality: ADS needs price data to build chaos chart

Natural Progression Steps:
  1. ADS calls PDSService.GetPriceHistory("EUR/USD", "H4", 300)
  2. PDS checks cache for recent data
  3. If stale, PDS fetches from data source
  4. Data normalized to PriceHistoryBase format
  5. Returned to ADS for indicator calculation

Achieved Outcome: Complete OHLCV data for analysis

Supporting Features: PDSPHistoryServices, data caching

Scenario 2: Batch Price Update

Creative Advancement Scenario: Update All Currency Pair Prices

Desired Outcome: Fresh H4 data for all USD pairs

Current Reality: Scheduled update needed for strategy monitoring

Natural Progression Steps:
  1. Scheduler triggers PDSEngine with "USD.pair H4"
  2. Engine resolves USD pairs from config
  3. Each pair's data fetched from source
  4. Data saved to JSON files in data directory
  5. Completion logged

Achieved Outcome: All USD pairs have current H4 data

Supporting Features: PDSEngine console app, ForexConnect API

Data Flow

┌─────────────────┐
│   Data Source   │
│ (ForexConnect)  │
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│   PDSEngine     │
│  (Batch Update) │
└────────┬────────┘
         │
         ▼
┌─────────────────┐     ┌─────────────────┐
│   JSON Files    │     │   SQL Database  │
│  (CDB-DTO Dir)  │     │   (Historical)  │
└────────┬────────┘     └────────┬────────┘
         │                       │
         └───────────┬───────────┘
                     ▼
              ┌─────────────────┐
              │   PDSService    │
              │   (Read API)    │
              └─────────────────┘

Timeframe Definitions

Code	Description	Bars/Day
m1	1 minute	1440
m5	5 minutes	288
m15	15 minutes	96
H1	1 hour	24
H2	2 hours	12
H3	3 hours	8
H4	4 hours	6
H6	6 hours	4
H8	8 hours	3
D1	1 day	1
W1	1 week	~0.2
M1	1 month	~0.03

Configuration

Supported Instruments

Standard Forex pairs with format {Base}-{Quote}:

Major: EUR-USD, GBP-USD, USD-JPY, USD-CHF
Cross: EUR-GBP, GBP-JPY, EUR-JPY, etc.
All pairs for: USD, EUR, GBP, JPY, CHF, AUD, NZD, CAD

Data Sources

ForexConnect API: Real-time and historical forex data
FXCM REST API: Alternative data source
Local Files: JSON/CSV cached data

Implementation Notes for Python/TypeScript

Python Implementation

from dataclasses import dataclass
from datetime import datetime
from decimal import Decimal
from typing import List, Optional

@dataclass
class PriceBar:
    date: datetime
    open: Decimal
    high: Decimal
    low: Decimal
    close: Decimal
    volume: int = 0

@dataclass
class PriceHistoryBase:
    instrument: str
    timeframe: str
    bars: List[PriceBar]
    start_date: datetime
    end_date: datetime
    source: str = "local"

class PDSService:
    async def get_price_history(
        self,
        instrument: str,
        timeframe: str,
        nb_bars: int = 300,
        dt_end: str = "now"
    ) -> PriceHistoryBase:
        """Retrieve price history for instrument"""
        pass
    
    async def refresh_prices(
        self,
        instruments: List[str],
        timeframe: str
    ) -> bool:
        """Update price cache from data source"""
        pass

TypeScript Implementation

interface PriceBar {
  date: Date;
  open: number;
  high: number;
  low: number;
  close: number;
  volume: number;
}

interface PriceHistoryBase {
  instrument: string;
  timeframe: string;
  bars: PriceBar[];
  startDate: Date;
  endDate: Date;
  source: string;
}

interface IPDSService {
  getPriceHistory(
    instrument: string,
    timeframe: string,
    nbBars?: number,
    dtEnd?: string
  ): Promise<PriceHistoryBase>;
  
  refreshPrices(
    instruments: string[],
    timeframe: string
  ): Promise<boolean>;
}