Skip to main content

​
Overview

ClyptQ uses TradingSpec to manage all configuration in a unified manner. A single spec file defines strategy, data, and execution environment, providing reproducible and shareable configuration.

​
TradingSpec Structure

from clyptq.apps.trading.spec import TradingSpec

spec = TradingSpec(
    # 1. Strategy definition
    strategy=StrategySpec(...),

    # 2. Data configuration
    data=TradingDataSpec(...),

    # 3. Execution configuration
    execution=TradingExecutionSpec(...),

    # 4. Account configuration
    accounts=[AccountSpec(...)],

    # 5. Symbol mapping
    symbol_source_map=SymbolSourceMap(...)
)

​
Strategy Configuration

ComputeGraph Definition: 
from clyptq.system.graph import ComputeGraph, Input

graph = ComputeGraph()

# Nodes
close = graph.add_node("close", FieldExtractor("close"))
sma_fast = graph.add_node("sma_fast", SMA(Input("close", lookback=10), span=10))
sma_slow = graph.add_node("sma_slow", SMA(Input("close", lookback=50), span=50))
signal = graph.add_node("signal",
    CrossoverAlpha(Input("sma_fast", lookback=1), Input("sma_slow", lookback=1))
)

# StrategySpec
strategy_spec = StrategySpec(
    graph=graph,
    signal_node="signal",  # Alpha signal node
    output_nodes=["signal", "sma_fast", "sma_slow"]  # Nodes to save
)
Save as Config File: 
# Save to YAML
spec.to_yaml("my_strategy.yaml")

# Load from YAML
spec = TradingSpec.from_yaml("my_strategy.yaml")

​
Data Configuration

Observation Specs: 
from clyptq.apps.trading.spec.observation import OHLCVSpec

data_spec = TradingDataSpec(
    observations=[
        OHLCVSpec(
            identifier="ohlcv_1m",
            venue="binance",
            market_type="futures",
            timeframe="1m",
            fields=["open", "high", "low", "close", "volume"]
        ),
        OHLCVSpec(
            identifier="ohlcv_1h",
            venue="binance",
            market_type="futures",
            timeframe="1h",
            fields=["open", "high", "low", "close", "volume"]
        )
    ],

    # Redis (optional)
    redis_mode=False,
    redis_url="redis://localhost:6379/0",
    redis_channel_prefix="live"
)
SymbolSourceMap: 
symbol_map = SymbolSourceMap(
    mappings={
        "BTC/USDT:USDT": ["ohlcv_1m", "ohlcv_1h"],
        "ETH/USDT:USDT": ["ohlcv_1m"]
    }
)

​
Execution Configuration

Backtest: 
execution_spec = TradingExecutionSpec(
    mode="backtest",
    venue="binance",
    market_type="futures",

    # Latency mode
    latency_mode="INSTANT",  # or "LATENT"

    # Fill model (LATENT only)
    fill_model="aggressive",  # or "passive"

    # Clock
    clock_freq="1m",  # Execution frequency
    clock_offset=0    # Offset (seconds)
)
Paper/Live: 
execution_spec = TradingExecutionSpec(
    mode="paper",  # or "live"
    venue="binance",
    market_type="futures",

    # API credentials (live only)
    api_key=os.getenv("BINANCE_API_KEY"),
    api_secret=os.getenv("BINANCE_API_SECRET"),

    # Risk limits
    max_position_size={"BTC/USDT:USDT": 10.0},
    max_position_pct=0.3,
    max_leverage=5.0,
    max_drawdown=0.20,

    # Order config
    default_order_type="market",  # or "limit"
    time_in_force="GTC"
)

​
Account Configuration

Spot Account: 
account = AccountSpec(
    type="spot",
    venue="binance",
    initial_balance={"USDT": 10000.0},

    # Cost model
    maker_fee=0.001,
    taker_fee=0.001,
    min_notional=10.0
)
Futures Account: 
account = AccountSpec(
    type="futures",
    venue="binance",
    initial_balance={"USDT": 10000.0},

    # Margin config
    margin_type="CROSS",  # or "ISOLATED"
    default_leverage=3.0,
    max_leverage=10.0,

    # Cost model
    maker_fee=0.0002,
    taker_fee=0.0004,
    funding_interval=28800  # 8 hours
)

​
Environment Variables

Required Settings: 
# Environment mode
export CLYPTQ_ENV=dev  # dev | prod | collector | kernel

# Storage paths
export CLYPTQ_DATA_ROOT=./data              # dev
export CLYPTQ_STORAGE_ROOT=/efs/data        # prod/collector
export CLYPTQ_BACKEND_URL=http://backend:8000  # kernel

# API credentials (live trading)
export BINANCE_API_KEY=your_key
export BINANCE_API_SECRET=your_secret

# Redis (optional)
export REDIS_URL=redis://localhost:6379/0
Optional Settings: 
# Logging
export LOG_LEVEL=INFO  # DEBUG | INFO | WARNING | ERROR

# Performance
export MAX_WORKERS=4  # Parallel execution workers

# Database (prod)
export DATABASE_URL=postgresql://user:pass@host/db

​
Complete Example

Backtest Configuration: 
from clyptq.apps.trading.spec import TradingSpec
from clyptq.apps.trading.spec.observation import OHLCVSpec

spec = TradingSpec(
    # Strategy
    strategy=StrategySpec(
        graph=create_momentum_strategy(),
        signal_node="signal"
    ),

    # Data
    data=TradingDataSpec(
        observations=[
            OHLCVSpec(
                identifier="ohlcv_1m",
                venue="binance",
                market_type="futures",
                timeframe="1m",
                fields=["close", "volume"]
            )
        ]
    ),

    # Execution
    execution=TradingExecutionSpec(
        mode="backtest",
        venue="binance",
        market_type="futures",
        latency_mode="LATENT",
        fill_model="aggressive",
        clock_freq="1m"
    ),

    # Account
    accounts=[
        AccountSpec(
            type="futures",
            venue="binance",
            initial_balance={"USDT": 10000.0},
            margin_type="CROSS",
            default_leverage=3.0
        )
    ],

    # Symbol mapping
    symbol_source_map=SymbolSourceMap(
        mappings={
            "BTC/USDT:USDT": ["ohlcv_1m"],
            "ETH/USDT:USDT": ["ohlcv_1m"]
        }
    )
)

# Save
spec.to_yaml("momentum_backtest.yaml")
Live Configuration: 
spec = TradingSpec(
    # Same strategy
    strategy=strategy_spec,

    # Same data (live mode)
    data=data_spec,

    # Live execution
    execution=TradingExecutionSpec(
        mode="live",
        venue="binance",
        market_type="futures",
        api_key=os.getenv("BINANCE_API_KEY"),
        api_secret=os.getenv("BINANCE_API_SECRET"),

        # Risk management
        max_position_pct=0.2,
        max_leverage=3.0,
        max_drawdown=0.15
    ),

    # Live account
    accounts=[
        AccountSpec(
            type="futures",
            venue="binance",
            # No initial_balance (use actual balance)
            margin_type="CROSS",
            default_leverage=3.0
        )
    ],

    symbol_source_map=symbol_map
)

spec.to_yaml("momentum_live.yaml")

​
Best Practices

1. Manage All Config with Spec 
# Good: Single spec file
spec = TradingSpec.from_yaml("strategy.yaml")
driver = TradingDriver.from_spec(spec)

# Bad: Hardcode in code
driver = TradingDriver(venue="binance", ...)
2. Separate Specs by Environment 
configs/
├── momentum_backtest.yaml
├── momentum_paper.yaml
└── momentum_live.yaml
3. Version Control 
spec = TradingSpec(
    version="1.0.0",  # Spec version
    description="Momentum crossover strategy",
    ...
)
4. Validation 
# Spec validation
spec.validate()  # Check required fields, verify logic

# Pre-execution validation
driver = TradingDriver.from_spec(spec)
driver.validate_before_run()  # Data availability, etc.
5. Secret Management 
# Good: Environment variables
api_key=os.getenv("BINANCE_API_KEY")

# Bad: Hardcode
api_key="my_secret_key"  # Never commit!
6. Risk Limits 
# Always configure
execution_spec = TradingExecutionSpec(
    max_position_pct=0.3,      # Max 30% of portfolio
    max_leverage=5.0,          # Max 5x
    max_drawdown=0.20,         # Stop at 20% loss
    ...
)

​
Migration

Backtest → Paper: 
# 1. Load backtest spec
backtest_spec = TradingSpec.from_yaml("backtest.yaml")

# 2. Change execution mode only
paper_spec = backtest_spec.copy()
paper_spec.execution.mode = "paper"

# 3. Save
paper_spec.to_yaml("paper.yaml")
Paper → Live: 
# 1. Load paper spec
paper_spec = TradingSpec.from_yaml("paper.yaml")

# 2. Convert to live
live_spec = paper_spec.copy()
live_spec.execution.mode = "live"
live_spec.execution.api_key = os.getenv("BINANCE_API_KEY")
live_spec.execution.api_secret = os.getenv("BINANCE_API_SECRET")

# 3. Tighten risk limits
live_spec.execution.max_position_pct = 0.1  # More conservative
live_spec.execution.max_drawdown = 0.10

# 4. Save
live_spec.to_yaml("live.yaml")

​
Ecosystem Integration

For Builders:
  • Share strategies via spec files
  • Reproducible configuration
  • Easy version control
For Buyers:
  • Transparent strategy configuration
  • Verify risk parameters
  • Guarantee identical settings