Quickstart

Build and backtest your first strategy in 5 minutes

1. Explore What’s Available

from clyptq import Helper

# What exchanges and market types are supported?
Helper.exchanges()

# What symbols can I trade on Binance futures?
symbols = Helper.symbols("binance", "futures", quote="USDT", limit=20)
print(symbols)
# → ['BTC/USDT:USDT', 'ETH/USDT:USDT', 'SOL/USDT:USDT', ...]

# What data do I have locally?
Helper.data_catalog()

2. Build the Graph

Every ClyptQ strategy is a directed acyclic graph (DAG) of operators. Data flows from FIELD inputs through operators to intentions:

Terms like StatefulGraph, FIELD, Input, and TaggedArray are explained in Core Concepts. For now, just follow the pattern — everything will make sense after reading that page.

from clyptq.system.graph import StatefulGraph, Input
from clyptq.apps.trading.operators.indicator import SMA
from clyptq.apps.trading.operators.signal import MomentumAlpha
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
from clyptq.apps.trading.spec.symbol_source_map import SymbolSourceMap

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

# --- Build graph ---
graph = StatefulGraph()

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

# Indicators: fast and slow SMA
graph.add_node("sma_fast", SMA(input=close, period=10))
graph.add_node("sma_slow", SMA(input=close, period=50))

# Signal: momentum alpha
graph.add_node("signal", MomentumAlpha(
    input=Input("sma_fast", "1m", lookback=2),
))

# Transform: equal weight allocation
graph.add_node("weights", EqualWeight(
    input=Input("signal", "1m", lookback=1),
))

# Portfolio: equity calculation
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"),
))

# Book size: 100% of equity for trading
graph.add_node("book", BookSize(
    input=Input("equity", "1m", lookback=1),
    min_book_size=100.0,
))

# Intention: convert weights to futures orders
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,
))

3. Configure the Spec

TradingSpec combines data, strategy, and execution into one configuration:

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

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, 6, 30),
    ),
    strategy=TradingStrategySpec(
        graph=graph,
        output_nodes=["equity"],  # Nodes to track for analysis
    ),
    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,  # Store results for to_dataframe()
)

4. Run the Backtest

from clyptq.apps.trading.driver import TradingDriver

driver = TradingDriver.from_spec(spec)

# The driver iterates tick by tick over the backtest period
equity_curve = []
for result in driver:
    if "equity" in result.outputs:
        equity_curve.append(result.outputs["equity"].value[0])

5. Analyze Results

# Convert any node's output to DataFrame (requires debug=True)
df_equity = driver.to_dataframe("equity")
df_equity.plot(title="Equity Curve")

df_sma = driver.to_dataframe("sma_fast")
print(df_sma.tail())

# Or export all output_nodes at once
results = driver.export_results(output_dir="./results", format="parquet")
print(results["state"])  # Account summary

6. Deploy to Paper or Live

Paper and live trading are not run from notebook cells. Once you’ve validated your strategy in backtest, submit it to the platform:

1. Submit your strategy code via the dashboard
2. The platform independently validates and backtests your strategy
3. Start a Paper Trade or Live Trade run from the dashboard — no code changes needed

The same StatefulGraph you built in your notebook runs identically in paper and live modes on the platform. See Backtest to Live and the Builder Guide for the full submission flow.

What’s Next?

FIELD/STATE Principles

Understand how data flows through the graph

Operator Reference

Browse operators: indicators, signals, transforms, AI

Backtesting Accuracy

Cost models, funding rates, liquidation simulation

First Strategy Tutorial

Extended tutorial with detailed explanations