Builder Guide

Strategy development and marketplace listing guide for strategy creators

Overview

This guide walks you through the full Builder workflow: develop a strategy in Jupyter, validate it through backtest → paper → live, and list it on the marketplace.

Why Build on ClyptQ?

Benefit	What You Get
Production Infrastructure	Data, execution engine, monitoring — ready to use
Code Parity	Same StatefulGraph runs in backtest, paper, and live. No rewrite needed
Python Freedom	Use PyTorch, XGBoost, HuggingFace, scipy — any library inside operators
Monetization	List strategies on marketplace — traders pay a one-time purchase price
Independent Verification	Platform verifies your backtest + runs cross-exchange validation

Template Format

When you submit a strategy to the marketplace, your .py file is executed inside ClyptQ’s validation sandbox. Your code must follow a specific contract for the platform to validate, backtest, and deploy it correctly.

ML/DL strategies: Currently, only the .py strategy file is submitted — external model files (.pkl, .pt, .onnx) cannot be uploaded. ML/DL workflows that require pre-trained models are supported in the research environment (Jupyter notebooks) but cannot yet be deployed to paper/live or listed on the marketplace. A workspace file explorer for model artifact management is planned.

The main() function

Every strategy must define a main() function that returns a TradingDriver. The platform calls this function to run your strategy.

New format (recommended) — receives mode and accounts from the platform:

def main(mode, accounts):
    """
    Args:
        mode: "backtest", "paper", or "live" — injected by the platform
        accounts: Dict mapping venue -> {"initial_cash": float}
                  e.g., {"binance:futures": {"initial_cash": 10000.0}}
    Returns:
        TradingDriver instance
    """
    graph = StatefulGraph()
    # ... build graph ...

    spec = TradingSpec(
        data=TradingDataSpec(...),
        strategy=TradingStrategySpec(graph=graph, output_nodes=["equity", "signal"]),
        execution=TradingExecutionSpec(
            accounts=[AccountSpec(
                exchange="binance",
                market_type="futures",
                base_currency="USDT",
                initial_cash=accounts["binance:futures"]["initial_cash"],
            )],
        ),
        mode=mode,   # Injected by the platform: "backtest", "paper", or "live"
        debug=True,
    )

    driver = TradingDriver.from_spec(spec)
    driver.warmup()

    return driver  # MUST return the driver

Old format — no parameters, uses injected global variables:

def main():
    initial_cash = __SANDBOX_INITIAL_CASH__  # Injected by the platform

    # ... build graph and spec ...
    driver = TradingDriver.from_spec(spec)
    driver.warmup()

    return driver  # MUST return the driver

main() must contain a return driver statement. The platform validates this at submission time — strategies without a return statement will be rejected.

Required metric operators

For marketplace listing, your graph must include three metric operators with exact node names. These operators are computed by ClyptQ’s internal code — the platform extracts final values from these nodes to display verified metrics to traders.

from clyptq.apps.trading.operators.metrics import (
    AccumSharpe,
    AccumMaxDrawdown,
    AccumTotalReturn,
)

# These three are REQUIRED — node names must match exactly
graph.add_node("sharpe", AccumSharpe(
    Input("equity", "1m", lookback=1), timeframe="1m",
))

graph.add_node("max_drawdown", AccumMaxDrawdown(
    Input("equity", "1m", lookback=1),
))

graph.add_node("total_return", AccumTotalReturn(
    Input("equity", "1m", lookback=1),
))

Node Name	Operator	What It Computes
"sharpe"	AccumSharpe	Incremental Sharpe ratio (Welford’s algorithm)
"max_drawdown"	AccumMaxDrawdown	Running peak-to-trough max drawdown
"total_return"	AccumTotalReturn	Cumulative total return

These metric operators are computed by ClyptQ’s internal code, not by user-supplied logic. This is how the platform guarantees that reported metrics are independently verified — builders cannot self-report or manipulate performance numbers.

Required output nodes

Your TradingStrategySpec.output_nodes must include "equity" at minimum:

TradingStrategySpec(
    graph=graph,
    output_nodes=["equity", "signal"],  # "equity" is REQUIRED
)

Node	Purpose
"equity"	Portfolio value over time (required)
"intention"	Trading signals and target positions (recommended)
"pnl"	Profit/loss tracking (recommended)
"drawdown"	Drawdown curve visualization (recommended)

Configuration parsed from your code

The platform automatically parses the following from your strategy code:

What	How It’s Detected	Example
Venues	SymbolSourceMap, AccountSpec, or "exchange:market_type" strings	"binance:futures"
Symbols	SymbolSourceMap dict values, or SYMBOLS variable	["BTC/USDT:USDT", "ETH/USDT:USDT"]
Timeframe	TIMEFRAME variable, or timeframe= in OHLCVSpec/Input	"4h"
Initial cash	initial_cash= in AccountSpec, or INITIAL_CASH variable	50_000.0
Base currency	base_currency= in AccountSpec	"USDT"

All venues in your SymbolSourceMap must have a matching AccountSpec with initial_cash. Strategies with missing cash configuration will fail validation.

Injected sandbox variables

During validation, the platform injects these variables into your execution environment:

Variable	Type	Description
__SANDBOX_CONFIG__	dict	Contains symbols, start, end, timeframe, initial_cash
__SANDBOX_INITIAL_CASH__	float	Target initial cash for validation
__SANDBOX_ACCOUNTS__	dict or None	Multi-venue accounts: {"binance:futures": {"initial_cash": 10000.0}}

During validation, the platform injects the capital level used for testing. Your code should use these values instead of hardcoding initial cash.

Ephemeral operators

Strategies using ephemeral (semantic) operators — LLMScorer, WebSearchOperator, SentimentParser — are handled differently:

• Backtesting is skipped entirely (these operators hit rate limits and produce non-reproducible results for historical data)
• Paper trading validation only is performed
• The strategy listing will display a badge indicating it uses AI/semantic operators

Sandbox security

The platform enforces multiple layers of security during strategy validation to protect the infrastructure and other users. Submitted code is analyzed and executed in an isolated environment with restricted capabilities.

Strategies that attempt to access system resources, network endpoints, or execute arbitrary code outside of the ClyptQ operator framework will be automatically rejected. The platform’s validation pipeline is designed to detect and block malicious or abusive patterns at multiple stages — from static analysis through runtime execution.

Focus on writing clean strategy logic using ClyptQ’s operator framework. If your code only uses ClyptQ imports, standard data science libraries (numpy, pandas, scipy, sklearn), and standard Python utilities (datetime, math, json, re, collections), it will pass validation without issues.

Template checklist

Requirement	Details
main() function exists	Defined at top level, returns TradingDriver
main() returns driver	Must have explicit return driver statement
"sharpe" node	graph.add_node("sharpe", AccumSharpe(...))
"max_drawdown" node	graph.add_node("max_drawdown", AccumMaxDrawdown(...))
"total_return" node	graph.add_node("total_return", AccumTotalReturn(...))
"equity" in output_nodes	Required for equity curve display
Symbols defined	SymbolSourceMap or SYMBOLS variable
AccountSpec with initial_cash	Required for each venue
Timeframe specified	TIMEFRAME variable or timeframe= parameter

Development Workflow

Step 1: Explore

Use the Helper class to discover what’s available:

from clyptq import Helper

# Available exchanges
Helper.exchanges()

# Futures symbols on Binance
symbols = Helper.symbols("binance", "futures", quote="USDT", limit=20)
# → ['BTC/USDT:USDT', 'ETH/USDT:USDT', 'SOL/USDT:USDT', ...]

# What data is cached locally?
Helper.data_catalog()

# Margin parameters (MMR, liquidation fee)
Helper.margin_info("binance")
# → default_mmr: 1.3%, liquidation_fee: 0.75%

Step 2: Build the Strategy Graph

Define symbol mapping

from clyptq.apps.trading.spec.symbol_source_map import SymbolSourceMap

symbol_source_map = SymbolSourceMap({
    "binance:futures": ["BTC/USDT:USDT", "ETH/USDT:USDT"],
})

Build the graph

from clyptq.system.graph import StatefulGraph, Input
from clyptq.apps.trading.operators.indicator import SMA
from clyptq.apps.trading.operators.transform import EqualWeight
from clyptq.apps.trading.operators.balance import EquityCalculator, BookSize
from clyptq.apps.trading.operators.order import FuturesTargetPositionIntention

graph = StatefulGraph()

# FIELD input — raw close prices from Binance futures
close = Input("FIELD:binance:futures:ohlcv:close", "1m", lookback=50)

# Indicators
graph.add_node("sma_fast", SMA(close, period=10))
graph.add_node("sma_slow", SMA(close, period=50))

# Signal — custom operator (user-defined BaseOperator subclass)
# Example: returns +1 when fast > slow, -1 otherwise
graph.add_node("signal", MySignalOperator(
    fast=Input("sma_fast", "1m", lookback=2),
    slow=Input("sma_slow", "1m", lookback=2),
))

# Transform — equal weight allocation
graph.add_node("weights", EqualWeight(),
    inputs=[Input("signal", "1m", lookback=1)])

# Portfolio accounting — uses STATE inputs
graph.add_node("equity", EquityCalculator(
    cash=Input("STATE:binance:futures:cash", "1m", lookback=0),
    positions=Input("STATE:binance:futures:pos_quantity", "1m", lookback=0),
    prices=Input("FIELD:binance:futures:ohlcv:close", "1m", lookback=0),
    entry_prices=Input("STATE:binance:futures:pos_entry_price", "1m", lookback=0),
    axis_keys=symbol_source_map.axis_keys_for("binance:futures"),
))

graph.add_node("book", BookSize(
    Input("equity", "1m", lookback=1), min_book_size=100.0,
))

# Order generation — target position intention
graph.add_node("intention", FuturesTargetPositionIntention(
    weights=Input("weights", "1m", lookback=1),
    book_size=Input("book", "1m", lookback=1),
    positions=Input("STATE:binance:futures:pos_quantity", "1m", lookback=0),
    prices=Input("FIELD:binance:futures:ohlcv:close", "1m", lookback=0),
    axis_keys=symbol_source_map.axis_keys_for("binance:futures"),
    execution_routing=symbol_source_map.execution_routing,
    leverage=3.0,
))

Key concepts:

• FIELD: inputs pull market data from exchanges
• STATE: inputs pull portfolio state from the executor (cash, positions, entry prices)
• Each Input declares its lookback — the number of historical ticks it needs
• The graph handles warmup, buffering, and execution order automatically

See Your First Strategy for a step-by-step walkthrough.

Step 3: Backtest

Configure and run

from datetime import datetime
from clyptq.apps.trading.spec.unified import TradingSpec
from clyptq.apps.trading.spec.unified import TradingDataSpec, TradingStrategySpec
from clyptq.apps.trading.spec.execution import TradingExecutionSpec, AccountSpec
from clyptq.apps.trading.spec.observation.crypto import OHLCVSpec
from clyptq.apps.trading.driver import TradingDriver

spec = TradingSpec(
    data=TradingDataSpec(
        symbol_source_map=symbol_source_map,
        observations=[OHLCVSpec(exchange="binance", market_type="futures", timeframe="1m")],
        start=datetime(2024, 1, 1),
        end=datetime(2024, 12, 31),
    ),
    strategy=TradingStrategySpec(
        graph=graph,
        output_nodes=["equity", "signal"],
    ),
    execution=TradingExecutionSpec(
        accounts=[AccountSpec(
            exchange="binance",
            market_type="futures",
            base_currency="USDT",
            initial_cash=10_000.0,
            max_leverage=3.0,
        )],
        execution_price_source="ohlcv",
    ),
    mode="backtest",
    debug=True,
)

driver = TradingDriver.from_spec(spec)
driver.warmup()

for result in driver:
    pass

# Analyze
df_equity = driver.to_dataframe("equity")
df_signal = driver.to_dataframe("signal")
df_equity.plot(title="Equity Curve", figsize=(14, 5))

Compare with zero-cost backtest

from clyptq.apps.trading.spec.execution import CostModelSpec

spec_zero = TradingSpec(
    ...  # same data and strategy
    execution=TradingExecutionSpec(
        accounts=[AccountSpec(
            exchange="binance", market_type="futures", base_currency="USDT", initial_cash=10_000,
            cost_model=CostModelSpec(maker_fee=0, taker_fee=0, slippage_bps=0),
        )],
    ),
    mode="backtest",
)

If the gap between zero-cost and real-cost returns is > 50% of gross return, your strategy may have excessive trading costs.

Step 4: Submit & Paper Trade

After validating your backtest, submit your strategy to the platform. Paper and live trading cannot be run from notebook cells — they are managed through the dashboard.

1. Submit your strategy via the marketplace submission flow
2. From the dashboard, start a Paper Trade run

What happens internally:

1. Historical warmup loads past data to fill all RollingBuffers
2. Clock syncs to the next real-time bar boundary
3. Live data arrives via WebSocket
4. Orders are executed with simulated fills (same fill model as backtest)

Step 5: Live Trading

From the dashboard, switch to Live mode and connect your exchange API credentials.

Safety features built in:

• Emergency shutdown: Stop from the dashboard to close all positions immediately
• Balance sync: Detects external changes (manual trades, liquidations, funding)
• First tick skip: Skips execution on the first real-time tick to avoid stale signals

Step 6: Marketplace Listing

What you submit

Builders submit a TradingSpec — not source code. The spec defines the complete strategy (graph, operators, connections, parameters) in a serializable format.

• Included: Graph structure, operator types, parameters, input connections, execution configuration
• Not included: Source code of custom operators (packaged as compiled modules)

Verification process

The platform independently verifies your strategy through automated validation: code validation, backtesting, multi-scale backtesting, and venue sampling (cross-exchange validation).

Marketplace Validation

Full details on each verification stage, consistency scoring, and how validation works

Listing requirements

• Strategy code passes validation (syntax + security checks)
• Required metric operators present (sharpe, max_drawdown, total_return)
• main() function exists and returns TradingDriver
• "equity" included in output_nodes
• All venues have matching AccountSpec with initial_cash

Pricing

Set your strategy’s price. Traders pay a one-time purchase fee, and the platform takes a commission based on your seller tier:

Seller Tier	Max Listing Price	Builder Revenue Share	Platform Commission
Free	$99	20%	80%
Bronze	$299	40%	60%
Silver	$599	60%	40%
Gold	$999	70%	30%

Tier progression (based on total revenue):

• Bronze: $10,000+ total revenue
• Silver: $40,000+ total revenue
• Gold: $70,000+ total revenue

Best Practices

Strategy development

• Keep it simple: Fewer parameters reduce the risk of overfitting
• Use universe filters: Don’t trade every symbol. Filter by volume and liquidity
• Minimize lookback: Smaller lookback = faster warmup + less memory
• Test across periods: Use out-of-sample testing. Don’t curve-fit to a single year

Backtesting

• Compare zero-cost vs real-cost: Check the fee impact on your returns
• Verify with funding costs: For futures, cumulative funding can erode profits significantly

Common pitfalls

Pitfall	Why It’s Dangerous	How ClyptQ Prevents It
Lookahead bias	Using future data in signals	RollingBuffer only exposes declared lookback history
Survivorship bias	Testing only current listings	Use point-in-time symbol lists
Overfitting	Too many parameters	Cross-exchange validation catches venue-specific overfitting
Ignoring costs	Profitable in theory, not in practice	Auto-injected exchange fees and funding rates
Ignoring funding	Slow bleed on long-hold futures	Auto-injected funding rate simulation

Related Pages

Your First Strategy

Step-by-step SMA crossover tutorial with detailed explanations

Backtest to Live

Full deployment lifecycle from backtest through paper to live

Marketplace

How the strategy marketplace verification works

Operator Reference

Browse all available operators