Quantitative core

Mathematical library

The authoritative, versioned formula catalogue — returns, PnL, True Range & ATR, volatility, momentum, moving averages, RSI, breakout and volume.

Clawlas never asks an LLM to compute a number. Prices, returns, volatility, PnL and every indicator come from this deterministic, versioned formula catalogue — pure functions with unit tests, explicit units and a defined treatment of missing data.

Price returns

returns_v1

Simple return

R_{t} = \frac{P _{t} - P _{t - 1}}{P _{t - 1}} = \frac{P _{t}}{P _{t - 1}} - 1

The intuitive percentage change between two prices — used for trade return, portfolio return and reporting.

$P_{t}$: price at time t
$P_{t - 1}$: price at the previous step

python

def simple_return(current: float, previous: float) -> float:
    if previous <= 0:
        raise ValueError("previous must be > 0")
    return (current / previous) - 1.0

returns_v1

Logarithmic return

r_{t} = ln (\frac{P _{t}}{P _{t - 1}})

Additive across periods and symmetric — the basis for volatility and statistical analysis.

returns_v1

Cumulative return

R_{c u m} = t = 1 \prod n (1 + R_{t}) - 1

Compounds a series of simple returns into one total return.

Trade PnL

Gross PnL for a Spot long is quantity times the price move; net PnL subtracts every cost. Clawlas always reports net.

pnl_v1

Gross PnL — Spot long

P n L_{g r oss} = Q (P_{e x i t} - P_{e n t r y})

$Q$: filled quantity
$P_{e n t r y}, P_{e x i t}$: entry and exit prices

Net PnL — what actually lands

+gross PnL
-entry feeEntryCost × f_entry
-exit feeExitValue × f_exit
-other costsnetwork, bridge, conversion, realized slippage

= net PnL

pnl_v1

Net return

R e t u r n_{n e t} = \frac{P n L _{n e t}}{E n t r y C os t + E n t r y F ee}

Net profit over the capital actually committed (entry cost plus the entry fee).

python

def net_return(net_pnl: float, entry_cost: float, entry_fee: float) -> float:
    return net_pnl / (entry_cost + entry_fee)

True Range & ATR

atr_v1

True Range

T R_{t} = max (H_{t} - L_{t}, ∣ H_{t} - C_{t - 1} ∣, ∣ L_{t} - C_{t - 1} ∣)

The largest of today's range and the gaps to yesterday's close — captures overnight jumps a high-minus-low misses.

$H_{t}, L_{t}$: high and low of the current candle
$C_{t - 1}$: previous close

atr_v1

Average True Range

A T R_{n} = \frac{1}{n} i = 0 \sum n - 1 T R_{t - i}

Average volatility over n periods (Wilder smoothing is also supported). Feeds stop distance and sizing — never a standalone signal.

python

def average_true_range(data, period: int = 14):
    tr = true_range(data)
    return tr.ewm(alpha=1 / period, adjust=False).mean()

Volatility

volatility_v1

Historical volatility

σ = \frac{1}{n - 1} i = 1 \sum n (r_{i} - \overset{r}{ˉ})^{2}

Standard deviation of returns. Local volatility drives stop distance and sizing; annualized volatility is mostly for comparison and reporting.

volatility_v1

Annualized volatility

σ_{ann} = σ_{p er i o d} N

$N$: periods per year for the timeframe

Volatility is bucketed into regimes per market, venue and timeframe:

Regime	Condition
Low	Current volatility < 30th percentile
Normal	30th ≤ current ≤ 80th percentile
High	Current volatility > 80th percentile
Extreme	Current volatility > 95th percentile

Momentum

momentum_v1

Rate of Change

R O C_{n} = \frac{P _{t} - P _{t - n}}{P _{t - n}}

Percentage move over n periods — the raw momentum measure.

momentum_v1

Volatility-normalized momentum

N or ma l i z e d M o m e n t u m = \frac{R O C _{n}}{σ _{n}}

Momentum expressed in units of volatility, so the same threshold means the same thing across calm and wild markets.

momentum_v1

Positive-return ratio

P R R = \frac{1}{n} i = t - n + 1 \sum t 1 (r_{i} > 0)

How many of the recent returns were positive. A high ratio means an orderly move, not one isolated candle.

$1 (\cdot)$: indicator: 1 if true, else 0

Moving averages & RSI

Trend filters and momentum confirmation only — never sufficient standalone entry signals.

ma_v1

Simple & exponential moving average

S M A_{n} = \frac{1}{n} i = 0 \sum n - 1 P_{t - i} E M A_{t} = α P_{t} + (1 - α) E M A_{t - 1}

$α = \frac{2}{n + 1}$: EMA smoothing factor

rsi_v1

Relative Strength Index

R S I = 100 - \frac{100}{1 + R S}, R S = \frac{G ain _{n}}{L oss _{n}}

Momentum confirmation and overextension detection. A given RSI never automatically implies a reversal.

Breakout

breakout_v1

Price breakout (current candle excluded)

C_{t} > max (H_{t - n}, \dots, H_{t - 1})

Close above the highest high of the prior n candles — the current candle is never part of the prior high.

breakout_v1

Breakout distance & volume ratio

B r e ak o u t D i s t = \frac{C _{t} - H H _{n}}{H H _{n}} V o l u m e R a t i o = \frac{V _{t}}{V _{n}} \geq θ

$H H_{n}$: previous highest high over n candles
$V_{n}$: median volume over n candles
$θ$: volume threshold

A valid breakout is a conjunction

Price breakout

\land

volume

\land

momentum

\land

liquidity

\land

acceptable spread, slippage and risk. Any single condition failing rejects the candidate — see Position sizing & stops and Liquidity & slippage.

Volume

volume_v1

Robust relative volume

R o b u s tR e l V o l = \frac{V _{t}}{median ( V ) _{n}}

Median, not mean — for new and skewed tokens a single print should not move the baseline.

volume_v1

Quote volume

Q u o t e V o l u m e = i \sum P_{i} Q_{i}

Value traded, comparable across assets — generally more useful than base-unit volume.

relative volume
quote volume
volume acceleration
volume concentration

Every formula is versioned

Each card carries a version tag (returns_v1, atr_v1, …). A trade stays reproducible even after a formula changes, because the version that produced it is pinned. Historical definitions are never overwritten in place — see Deterministic scripts.