TradingCalc

Compound annual growth rate between a beginning and an ending value over a number of years: the constant yearly rate that turns one into the other, (ending / beginning)^(1 / years) - 1. A smoothed average: it hides the path and the volatility in between, and it says nothing about future growth. Both values must be positive. Use when user asks "what is the CAGR of my portfolio?" or "what yearly growth takes $10,000 to $25,000 in 8 years?". Returns: cagr, totalReturn, growthMultiple, logGrowthRate (all fractions; logGrowthRate is the continuously compounded rate).

workflow.run_cagr

Delta-neutral carry trade (funding arbitrage) analysis, with a profitable/marginal/loss verdict on top of the same math primitive.funding_arb uses. Compared with primitive.funding_arb, this one adds output for the case where a plain-English verdict is wanted, not just the raw numbers. Use when user asks "is this carry trade worth it?": long on exchange A, short on exchange B, collect the funding rate spread. Returns: netYieldPct, grossProfit, netProfit, breakevenDays, verdict (profitable/marginal/loss).

workflow.run_carry_trade

Engle-Granger two-step cointegration test for a pair of price series: do they share a long-run equilibrium relationship (their spread is stationary/mean-reverting)? The standard pairs-trading signal test. Returns the cointegrating regression's hedge ratio (beta) and an ADF t-statistic on the residuals, compared against 1%/5%/10% critical values. Use when user asks "are these two assets cointegrated?" or "is this a valid pairs trade?". Returns: alpha, beta (hedge ratio), t_stat, critical_values, cointegrated (booleans at each significance level).

workflow.run_cointegration

Project capital growth from reinvesting perpetual futures funding income (compounding carry). Use when user asks "how much will I make compounding 0.01% funding for 90 days?" or "what's my APY on this carry position?". Funding received is split by reinvestPct (the rest is withdrawn and still counts as earned); funding paid comes out of capital in full, and the capital never goes below 0. Returns: finalCapital, totalWithdrawn, endValue, totalEarned, totalEarnedPct, annualizedAPY, dailyEarnings, snapshots.

workflow.run_compound_funding

Covered call (long the coin + short a call against it, for yield) or protective put (long the coin + long a put, for downside insurance) on a Deribit BTC/ETH position. Returns the standard annualized-yield metric (premium ÷ 1 coin, annualized by 365/daysToExpiry) up front: that number doesn't depend on any price scenario. Also returns the USD value of the combined position at a given scenario price: covered call caps upside at strike + premium×scenarioPrice (the premium's own coin-denominated value still scales with price, unlike a textbook USD-settled cap); protective put floors value at strike×(1−premium), which is the true minimum across every possible settlement price, not just an approximation. Use when user asks "what annualized yield do I get selling covered calls on my BTC?" or "how much does insuring my BTC with a put cost me?". Returns: staticYieldPct, annualizedYieldPct, valueAtScenarioUsd, breakevenPrice (covered_call only), floorValueUsd (protective_put only), vsHoldingUsd (vs. just holding the coin).

workflow.run_covered_call_protective_put

Checks 2-5 quotes for the SAME real-world binary bet across venues (or manually-supplied probabilities) for a direction-independent price gap at the quoted prices: "Yes" at whichever venue quotes it cheapest, "No" at whichever venue quotes "Yes" most expensively (its own "No" price is assumed to be 1 minus its own "Yes" price, the standard complementary-binary convention). Reports isArbitrage, the cost to lock in $1 of guaranteed payout, the locked-in profit and ROI at the quoted prices for a given stake, and which venue quotes each side. feePctPerLeg is an optional per-leg trading-fee rate that can and does erase a real-looking spread - reported honestly via isArbitrage rather than always showing a positive number. Use when user asks "can I arbitrage this bet across venues?" or "does the quoted price gap survive fees?". The caller asserts the venues quote the same bet; this tool does not verify that. If available is false, do not use any result field (computed figures and any verdict are null or empty), so read available first.

workflow.run_cross_venue_arbitrage

Profit or loss on a spot crypto trade (coins bought and sold outright, no leverage, no funding) after both fees. Give exactly one of investment (total cash spent, buy fee included) or quantity (coins bought). Each fee is a fraction of that fill's trade value (0.001 = 0.1%): the buy fee is paid on top of the coins' cost, the sell fee comes out of the sale value. For a leveraged perpetual futures position see workflow.run_pnl_planning. Use when user asks "I bought BTC at $X, what is my profit if I sell at $Y?" or "what price do I need to sell at to break even after fees?". Returns: quantity, totalCost, proceeds, totalFees, profit, roiPct and priceChangePct (fractions), priceMultiple, breakevenSellPrice, annualizedReturnPct (a fraction, only when holdingDays is given and is at least 30, null otherwise: annualizing a shorter hold gives meaningless figures).

workflow.run_crypto_profit

DCA entry planner: weighted average entry price, breakeven, and per-level contribution from multiple fill prices and sizes. Each fill is { price, size } here (primitive.average_entry calls the same field quantity). Compared with primitive.average_entry, this one adds output for the case where breakeven or the per-level breakdown is also wanted, not just the bare average. Use when user bought at several prices and asks "what's my average entry?" or "where is my DCA breakeven?". Returns: averageEntry, breakeven, per-level summary.

workflow.run_dca_entry

Deflated Sharpe Ratio (Bailey & Lopez de Prado): given how many strategy variants you tried (and how correlated they are), what Sharpe ratio would the *best of N* clear by luck alone, and does your actual strategy still clear that higher bar? Use when user asks "is my backtested Sharpe ratio real, or did I get lucky trying many variants?" or "how many independent trials does this really represent?". Provide either trial_sharpes[] (the N trials' own observed Sharpe ratios, most rigorous) or n_trials (+ optional avg_correlation to correct for correlated trials via Kish's design effect). Two limits to know. n_trials assumes the paper's illustrative case (trial Sharpes with mean 0 and variance 1, in per-period units), which is a very high bar for a low-frequency series: the threshold is about 1.6 at N=10, 2.5 at N=100 and 3.3 at N=1000, while a daily series has a per-period Sharpe of order 0.05, so dsr comes out effectively 0; use trial_sharpes there. trial_sharpes centers the threshold on the trials' own mean Sharpe plus their dispersion times the expected-maximum factor; this answers "does my strategy beat the best of N trials drawn from the spread I observed", not the zero-skill-null variant; pass null_mean true for that variant (mean fixed at 0, spread still taken from the trials); the two thresholds differ by exactly the trials' mean Sharpe. Returns: expected_max_sharpe (the luck-alone threshold), dsr (probability your strategy's true Sharpe exceeds it, 0-1), n_trials_effective.

workflow.run_dsr

Extreme Value Theory tail risk (Peaks-Over-Threshold): fits a Generalized Pareto Distribution to the losses beyond a high threshold via Grimshaw's (1993) profile-likelihood MLE, then extrapolates VaR/Expected Shortfall at the requested confidence, without assuming a normal distribution. Use when user asks "what's my tail VaR without assuming normality?" or "how fat is my loss tail, really?". Complements workflow.run_var_cvar (parametric, normal-distribution VaR/CVaR) for exactly the fat-tailed-return case that assumption understates. threshold_percentile (default 90) sets which percentile of the loss distribution (losses = -returns) becomes the threshold u; confidence must be deep enough into the fitted tail (1-confidence < the threshold's own exceedance rate) or the call throws. Returns: threshold, n_exceedances, exceedance_rate, xi (GPD shape: 0=exponential tail, >0=heavy/fat tail, <0=bounded tail; values <= -1 are excluded from the fit domain as a known non-regular/unbounded-likelihood case, Smith 1985), beta (GPD scale), xi_asymptotically_normal (false when xi<=-0.5: the fit is still valid but the usual MLE confidence-interval theory doesn't apply, per that same Smith 1985 result), var, es (null when xi>=1, where Expected Shortfall is mathematically undefined).

workflow.run_evt_tail_risk

Calculate the exact exit price needed to hit a target PnL or ROE percentage. Use when user asks "at what price do I take profit to make $500?" or "where should I set TP for 20% ROE?". Returns: targetExitPrice.

workflow.run_exit_target

Fibonacci retracement and extension price levels from a swing high and low, for any asset (forex, stocks, crypto): retracement 0, 23.6, 38.2, 50, 61.8, 78.6 and 100 percent and extension 127.2, 161.8, 200 and 261.8 percent, as prices. direction "up" measures a rise from the low to the high, "down" a fall from the high to the low; 0 percent is the end of the swing and 100 percent its start. A level at or below zero (an extension of a steep fall) comes back as price null. The ratios are a charting convention, not a forecast. Pure price arithmetic, no pair or market data.

workflow.run_fibonacci_levels

Size-weighted average entry price across multiple forex fills: plain arithmetic mean, since forex has no coin-margined analog requiring the harmonic mean the crypto average_entry tool uses for inverse contracts. Use when user asks "what's my average entry after these fills?". Returns: totalUnits, totalCost, avgEntry.

workflow.run_forex_average_entry

Breakeven price for a forex position accounting for spread and round-trip commission, in pips and in price. Commission is quoted per standard lot (100,000 units) and expressed in the pair's own quote currency; because both commission and pip value scale with lot size, the commission-in-pips figure is independent of position size by construction. Precious-metal pairs (XAU, XAG, XPT, XPD) are refused with an error, because their pip and lot size differ by broker. Use when user asks "where's my true breakeven after spread and commission?". Returns: pipSize, commissionPips, totalCostPips, breakevenPrice.

workflow.run_forex_breakeven

Correlation coefficient and minimum-variance hedge ratio between two price series of matching length, computed on daily % returns (not raw price levels, which would give spuriously high correlation between two unrelated but both-trending series). hedgeRatio follows Hull's standard futures-hedging formula: cov(returns1,returns2)/var(returns2), "how many units of series 2 per unit of series 1 minimizes the combined position's variance." No live data fetch: supply the two price series directly. The live variant is workflow.run_forex_correlation_live, which has both series fetched automatically for two named pairs. Use when user already has two price series and wants their statistical relationship. Returns: n, correlation (-1 to 1), hedgeRatio.

workflow.run_forex_correlation

Correlation coefficient and minimum-variance hedge ratio between two forex pairs, fetched live: historical daily rates for both pairs over the given lookback window (frankfurter.app's daily ECB reference time series, business days only), aligned by matching date, computed on daily % returns. hedgeRatio follows Hull's standard futures-hedging formula: "how many units of pair2 per unit of pair1 minimizes the combined position's variance." Use when user asks "how correlated are EUR/USD and GBP/USD?" or "what hedge ratio should I use between these two pairs?". Returns: n (overlapping trading days used), correlation (-1 to 1), hedgeRatio, available (false + error if either pair has no data, or too few dates overlap). If available is false, do not use any result field (computed figures and any verdict are null or empty), so read available first.

workflow.run_forex_correlation_live

Converts an amount between currencies using a manually supplied rate: no live data fetch. The live variant is workflow.run_forex_currency_converter_live, which has the rate fetched automatically. Use when user already knows the exact rate they want applied. Returns: converted.

workflow.run_forex_currency_converter

Converts an amount between currencies using a live FX rate: TrueFX for its 10 quoted majors (genuinely live tick data), frankfurter.app daily ECB reference rate as the fallback for every other currency pair (30 total). Use when user asks "what's $X worth in EUR?" or any currency conversion where the rate itself isn't already known. Returns: converted, rate, source (truefx/frankfurter/identity), asOf, available (false + error if no rate could be found for that pair). If available is false, do not use any result field (computed figures and any verdict are null or empty), so read available first.

workflow.run_forex_currency_converter_live

Free margin and margin level % from account equity and used margin: equity/usedMargin*100, the same stop-out proximity metric every forex platform shows. Returns null (not Infinity) when usedMargin is 0, meaning no open position. Use when user asks "how close am I to a margin call?" or "what's my free margin?". Returns: freeMargin, marginLevelPct.

workflow.run_forex_margin_level

Notional and margin required for a forex position, in the pair's own quote currency: no live FX rate needed. Never built for Phase 1 of this domain since a margin figure has no natural currency-neutral form the way pip value does. The live variant is workflow.run_forex_margin_required_live, which applies when the account currency differs from the pair's quote currency. Use when user asks "how much margin do I need for X lots of EUR/USD at 50:1?". Returns: notionalQuote, marginQuote, base, quote.

workflow.run_forex_margin_required

Notional and margin required for a forex position, converted to a given account currency via a live FX rate (same TrueFX/frankfurter.app source as workflow.run_forex_pip_value_live). Use when user asks "how much margin do I need in my account currency?" and the account currency differs from the pair's own quote currency. Returns everything workflow.run_forex_margin_required does, plus accountCurrency, notionalAccount, marginAccount, fxRate, fxSource, available (false + error if no rate could be found). If available is false, do not use any result field (computed figures and any verdict are null or empty), so read available first.

workflow.run_forex_margin_required_live

Value of 1 pip for a given forex pair and position size, in that pair's own quote currency (e.g. EUR/USD's pip value comes back in USD, USD/JPY's in JPY): no live FX rate needed, since a pair's pip value is naturally denominated in its own quote currency. Pip size is 0.0001 for non-JPY pairs, 0.01 for JPY-quoted pairs, a universal market convention verified against real broker documentation, not broker-specific. The live variant is workflow.run_forex_pip_value_live, which applies when the account currency differs from the pair's quote currency. Precious-metal pairs (XAU, XAG, XPT, XPD) are refused with an error, because their pip and lot size differ by broker. Use when user asks "what's 1 pip worth on X lots of EUR/USD?". Returns: pipSize, pipValueQuote, base, quote.

workflow.run_forex_pip_value

Value of 1 pip for a forex pair and position size, converted to a given account currency via a live FX rate: TrueFX for its 10 quoted majors (genuinely live tick data), frankfurter.app daily ECB reference rate as the fallback for every other currency (30 total). Precious-metal pairs (XAU, XAG, XPT, XPD) are refused with an error, because their pip and lot size differ by broker. Use when user asks "what's 1 pip worth in my account currency?" and the account currency differs from the pair's own quote currency (if it matches, workflow.run_forex_pip_value alone is enough, no live fetch needed). Returns everything workflow.run_forex_pip_value does, plus accountCurrency, pipValueAccount, fxRate, fxSource (truefx/frankfurter/identity), available (false + error if no rate could be found for that currency). If available is false, do not use any result field (computed figures and any verdict are null or empty), so read available first.

workflow.run_forex_pip_value_live

Profit or loss for a closed or hypothetical forex trade, in pips and in the pair's own quote currency, long or short. Precious-metal pairs (XAU, XAG, XPT, XPD) are refused with an error, because their pip and lot size differ by broker. Use when user asks "what did I make/lose on this trade?" or "what would X pips be worth on Y lots?". Returns: pips (signed, positive favors the position taken), pnlQuote.

workflow.run_forex_pnl

Position size (units and standard lots) from a risk amount and stop distance, in a given account currency, via a live FX rate to convert pip value into that currency (same TrueFX/frankfurter.app source as the other forex _live tools). Never has a meaningful account-currency-agnostic form: sizing a position from a risk budget genuinely requires knowing what 1 pip is worth in the currency that budget is denominated in. Precious-metal pairs (XAU, XAG, XPT, XPD) are refused with an error, because their pip and lot size differ by broker. Use when user asks "how many lots should I trade to risk $X on this setup?". Returns: stopDistancePips, units, lots, pipValuePerUnitAccount, fxRate, fxSource, available (false + error if entry equals stop, or if no rate could be found). If available is false, do not use any result field (computed figures and any verdict are null or empty), so read available first.

workflow.run_forex_position_size_live

Risk and reward distance in pips from entry/stop/target, and the resulting ratio (reward/risk): a raw number, not a verdict. ratio is null when the stop sits exactly at entry (no risk distance), and also when validSetup is false (stop/target on the wrong side of entry for the given side, e.g. a long with its stop above entry) - check validSetup before trusting the ratio. Precious-metal pairs (XAU, XAG, XPT, XPD) are refused with an error, because their pip and lot size differ by broker. Use when user asks "what's my risk/reward on this setup?". Returns: riskPips, rewardPips, validSetup, ratio.

workflow.run_forex_risk_reward

PnL across a range of hypothetical price moves (in pips, signed by actual price direction, not pre-adjusted for side), for a single forex position size, long or short. Precious-metal pairs (XAU, XAG, XPT, XPD) are refused with an error, because their pip and lot size differ by broker. Use when user asks "what if price moves X pips in either direction?". Returns: scenarios[] (deltaPips, exitPrice, pnlQuote).

workflow.run_forex_scenario

Total swap/rollover cost (or credit) for holding a forex position overnight, in the pair's own quote currency: no live FX rate needed. Swap rates are broker-set with no free live feed available, so swapPerLotPerNight is always a manual input (quoted per standard lot, matching how commission is quoted in workflow.run_forex_breakeven), not fetched. Negative = cost (you pay), positive = credit (you receive). The live variant is workflow.run_forex_swap_cost_live, which applies when the account currency differs from the pair's quote currency. Precious-metal pairs (XAU, XAG, XPT, XPD) are refused with an error, because their pip and lot size differ by broker. Use when user asks "how much will holding this position overnight cost me?". Returns: lots, totalSwapQuote, base, quote.

workflow.run_forex_swap_cost

Total swap/rollover cost (or credit) for holding a forex position overnight, converted to a given account currency via a live FX rate (same TrueFX/frankfurter.app source as the other forex _live tools). swapPerLotPerNight is still always a manual input: swap rates are broker-set, with no free live feed available for them. Precious-metal pairs (XAU, XAG, XPT, XPD) are refused with an error, because their pip and lot size differ by broker. Use when user asks "how much will holding this position overnight cost me in my account currency?" and it differs from the pair's own quote currency. Returns everything workflow.run_forex_swap_cost does, plus accountCurrency, totalSwapAccount, fxRate, fxSource, available (false + error if no rate could be found). If available is false, do not use any result field (computed figures and any verdict are null or empty), so read available first.

workflow.run_forex_swap_cost_live

Calculate funding rate arbitrage profit: annualized yield, net profit, and breakeven days for a long/short basis trade across two exchanges: the bare numbers only, no plain-English verdict. For the same math plus a profitable/marginal/loss verdict, use workflow.run_carry_trade instead. Use when user asks "is this funding arb worth it?" or "how many days to break even on transfer fees?". Returns: netProfitUsdt, annualizedYieldPct, breakevenDays.

workflow.run_funding_arbitrage

Price move needed to cover funding cost + fees over a holding period. Use when user asks "how much does BTC need to move for me to profit after funding?" or "is funding killing my edge on this trade?". Returns: breakevenWithFunding, breakevenWithoutFunding, requiredMovePct.

workflow.run_funding_breakeven

Calculate the total funding cost (or income) for holding a perpetual futures position. Use when user asks "how much funding will I pay holding X days?" or "is funding eating my profit?". Returns: totalCost (positive = you pay, negative = you receive; in the coin for inverse), costPerDay, annualPct, totalPeriods, breakevenShift (size of the price move whose PnL equals the funding: up for a positive rate, down for a negative one, for either side).

workflow.run_funding_cost

Future value of a starting sum, regular contributions, or both, grown at a fixed rate: what savings or an investment reach after a number of years. annualRate is a fraction (0.07 = 7%) split into periodsPerYear equal periods the nominal way (rate per period = annualRate / periodsPerYear); years x periodsPerYear is the number of periods, which must be whole when a payment is given. Contributions are level and made at the end of each period, or at the start with paymentTiming "begin". A fixed assumed rate, not a forecast and not a market-return simulation (for a range of outcomes use workflow.run_monte_carlo). Use when user asks "what will $10,000 plus $500 a month be worth in 30 years at 7%?" or "how much will I have after 10 years of saving?". Returns: futureValue, fvOfPresentValue, fvOfPayments, growthFactor, ratePerPeriod, periods, totalContributions, interestEarned, effectiveAnnualRate.

workflow.run_future_value

GARCH(1,1) volatility model, fit by maximum likelihood on a return series: estimates omega/alpha/beta (the variance-persistence parameters) and forecasts next-period volatility. Use when user asks "what's my GARCH volatility forecast?" or "how persistent is volatility in this return series?". This is a backward-looking statistical fit, not a market prediction guarantee. Returns: mu, omega, alpha, beta, persistence (alpha+beta), unconditional_vol, forecast_vol, loglikelihood.

workflow.run_garch

Calculate the short perpetual futures position size needed to hedge a spot holding. Default USDT-linear: sizes and costs in USD. With contractType "inverse" (coin-margined, needs entryPrice) the short is the same USD contracts and margin and funding come back in the base coin. Use when user asks "how much should I short to hedge my BTC?" or "what margin do I need for a 100% hedge?". Returns: perpNotional, requiredMargin, dailyFundingCost, annualFundingCost, hedgeCoverage, contractType and costUnit ("USD", or "base_coin" for inverse: read it before showing margin or funding as dollars). Inverse converts at the one entryPrice you give, so the coin figures assume the price stays there.

primitive.hedge_ratio

Hurst exponent via rescaled-range (R/S) analysis: is this return/price series trending/persistent (H>0.5, a move tends to be followed by a move in the same direction), mean-reverting/anti-persistent (H<0.5), or consistent with a random walk (H~0.5)? Use when user asks "is this asset trending or mean-reverting?" or "does this series show long-range dependence?". Takes a return series, not raw price levels. Returns: hurst, interpretation (trending/mean_reverting/random_walk), window_sizes, rs_values.

workflow.run_hurst_exponent

Impermanent loss for a liquidity-pool position: compares providing liquidity against simply holding the same tokens, at a manually-supplied entry and current price. Two modes: full_range (standard 50/50 constant-product pool, the textbook 2*sqrt(k)/(1+k)-1 closed form) or concentrated (a Uniswap-V3-style position confined to [lowerPrice, upperPrice] - IL is always worse than full_range for the same price move when the range is tight, and the position is fully single-asset, no longer earning fees, once price exits the range). impermanentLossPct is always <= 0 and is measured relative to the quote token (dimensionless, exact regardless of what the quote token is); the optional dollar figures additionally assume the quote token's own USD price stayed roughly stable (true for a stablecoin-quoted pool). Use when user asks "how much am I losing to impermanent loss?" or "is this LP position still worth it after fees?". Returns: impermanentLossPct, lpValueMultiplier, hodlValueMultiplier, inRange, lossUsd/netResultUsd (null unless depositValueUsd given).

workflow.run_impermanent_loss

Live variant of workflow.run_impermanent_loss: fetches each token's current live USD price (Solana or any of 5 EVM chains) and derives currentPrice as their ratio, instead of it being supplied manually. entryPrice stays a manual, historical input (a fact the caller must supply, not something a live quote should overwrite), same convention as every other live-capable tool in this product. Use when the caller has the pool's two token addresses but doesn't already know the current price ratio. Returns the same fields as workflow.run_impermanent_loss, plus currentPrice, baseSymbol, quoteSymbol, routable (false + error if either token's price can't be resolved).

workflow.run_impermanent_loss_live

Solves for the volatility that makes Black-Scholes reproduce an observed option price (Newton-Raphson with a bisection fallback for cases where vega is too flat to converge, e.g. deep ITM/OTM or very short-dated). Checks the price against its no-arbitrage bounds first and refuses to solve (converged: false + error) rather than return a garbage number when the price is impossible for the given spot/strike/rate. Use when user asks "what IV does this option price imply?" or gives a market price and wants the volatility, not the reverse. Returns: impliedVolatilityPct, iterations, method (newton-raphson/bisection), converged, identifiable, warning, priceAtSolution. identifiable is false when many volatilities reproduce the price (deep ITM, far OTM): warning then says the returned volatility is one of them. When converged is false, identifiable is false and error explains.

workflow.run_implied_volatility

Internal rate of return: the rate per period at which the NPV of a list of cash flows is zero (first flow at time 0). The flows need at least one outflow and one inflow. One sign change in the flows (all outflows first, then all inflows) gives exactly one answer, returned as irr with unique true. With several sign changes there can be several rates or none: every rate found is listed in irrs and irr is null even when only one rate was found (reason "unverified"), with reason "multiple_roots" or "none_found" otherwise, so do not quote one rate as the return. With one sign change the search reaches about 1e13 per period; beyond that reason is "none_found". The search covers rates from -99% to +9,900% per period on a 0.2% grid of ln(1 + rate); two roots closer than that, or a root where NPV only touches zero, can be missed. Give periodsPerYear to also get the annual effective rate. Use when user asks "what is the IRR of these cash flows?" or "what return does this project earn?". Returns: irr, irrs, unique, signChanges, reason, annualEffectiveRate, periods.

workflow.run_irr