TradingCalc MCP: Options, Forex, Risk Stats, Prediction Markets, On-Chain & Crypto Futures MCP Server

Price of an AMERICAN put or call (exercisable on any day up to expiry) on a Cox-Ross-Rubinstein binomial tree with early exercise checked at every node, with a continuous dividend yield. Use it for stock and ETF style options; crypto options on Deribit and Binance are European (`workflow.run_black_scholes`). Output: americanPrice, delta, gamma, thetaPerDay (calendar day, read from the tree, typically 0 when exercising now is optimal), intrinsicValue, earlyExerciseNow (a tree reading: exercising now beats holding), europeanPrice (Black-Scholes, same inputs), earlyExercisePremium, europeanTreePrice and treeError (what the chosen step count costs: the same tree without early exercise minus the exact European price). More steps are closer to the exact value, not smoothly. Rates 0 to 100 percent, dividend yield is a continuous yield, not dated dividends; steps are a whole number from 50 to 2000 (default 500). Prices are USD per unit of underlying. Edge cases: spot, strike, daysToExpiry (at most 3650) and volatilityPct (at most 300) above zero; steps a whole number from 50 to 2000; when the rate and the dividend yield are too far apart for the volatility and expiry the tree is invalid and the call is an error that says so; numbers that overflow are an error. The price is a tree value, close to the exact one but not equal to it (see treeError). Not covered: discrete dividends, a volatility smile, negative rates, taxes, margin, transaction costs, and exercise limited to certain dates (Bermudan).

Convert an APR (nominal yearly rate) to an APY (effective yearly rate) or back, for a compounding you choose. APY = (1 + APR / m)^m - 1 for m periods a year, e^APR - 1 when continuous. The same APY is a different APR at every compounding frequency, so the frequency is required: give periodsPerYear (365 daily, 12 monthly) or continuous true, not both. Rates are fractions (0.12 = 12%). It converts rate arithmetic only: it does not include fees, token price moves or the risk that a pool rate changes. Edge cases: rate a fraction from -periodsPerYear (APR) or above -1 (APY) up to 1000; give periodsPerYear (1 to 365) or continuous true, never both and never neither; the rate per period must stay above -100%; a continuous APR above 709 (70,900%) is an error. Not covered: fees, token price moves, a pool rate that changes, taxes, and compounding that is not regular. Use when user asks "what APR is an 8% APY compounded daily?" or "what is 12% APR monthly as an APY?". Returns: apr, apy, periodsPerYear, continuous, ratePerPeriod, apyMinusApr, byCompounding (the same APY as an APR at annual, semiannual, quarterly, monthly, weekly, daily and continuous compounding).

Real entry price of a spot coin bought and sold in several trades: moving average cost, trades in the order they happened, each with its own fee (no leverage, no funding). The buy fee is part of the cost basis; a sale removes coins at the current average and never changes the average of what is left, only a later buy does; selling everything resets it. Selling more than is held at that point is an error naming the trade. Each fee is a fraction of that trade's value (0.001 = 0.1%, at most 0.05). Edge cases: 1 to 1000 trades; price and quantity above zero; a sale before any buy, or above the holding, is an error; a sale within 1e-12 of the largest holding since the position was last flat counts as selling everything (float noise) and leaves exactly zero, never a residual; when nothing is held the average, before-fee average and break-even are null and costBasis is 0; realizedProfit can be negative. Not covered: taxes, FIFO/LIFO lots (moving average cost only), slippage, withdrawal or network fees, currency conversion, leverage and funding. Prices may be in any currency; results are in the same one. sellFeePct is the fee expected when the remaining coins are sold, used for the break-even sell price. For equal cash buys at a list of prices use workflow.run_spot_dca; for the average entry of a perpetual futures position use primitive.average_entry. Use when user asks "I bought and sold this coin several times, what is my average buy price and break-even now?". Returns: remainingQuantity, averageBuyPrice (fees in) and averageBuyPriceBeforeFees (null when nothing is held), costBasis, totalBought, totalSold, totalInvested, totalSellProceeds, realizedProfit, totalFees, breakevenSellPrice (null when nothing is held).

Should-I-average-down check: for an already-open position, compares adding more at a worse price against the always-available alternative of buying the same final total size fresh at today's price. Returns the new blended average entry, liquidation price and breakeven (before vs. after), margin_added (the actual cash/margin required for the add at this leverage, not the full notional), and three risk figures at your stop-loss: existing_risk (what you already risk, before adding), pyramid_risk (what you'd risk after adding), and clean_entry_risk (what a fresh entry at add_price for the same total size would risk). risk_penalty_pct is how much MORE than that fresh-entry alternative you're risking - for any genuine average-down (add_price worse than existing_entry_price) pyramid_risk is provably always greater than clean_entry_risk. liquidation_before_stop is true when the new liquidation price sits at or beyond your own stop-loss, meaning the exchange would force-close the position before the stop-loss ever triggers. Edge cases: all prices, sizes, stop_loss and leverage above zero; fee_open_pct and fee_close_pct are fractions from 0 to 0.05 (defaults 0.0002 and 0.0005); mmr 0 to 0.2; for a long the stop must be below the add price and for a short above it, otherwise an error (a stop that price already reached means the position should be closed). The risk comparison is meaningful only when the add is at a worse price than the existing entry. Not covered: funding, slippage, a stop that gaps through, and whether the market will recover. Use when user asks "should I add to this losing position?" or "what does averaging down actually cost me here?". liquidation_price and the liquidation distance are null when the position cannot be liquidated (an inverse short at 1x or less): check for null before using them.

Probability that the price touches a barrier (a target or a stop level) at ANY time within N days, under geometric Brownian motion (reflection principle with drift). This is not the probability of finishing beyond the level at expiry: at zero log-drift a touch is exactly twice as likely as a finish, and `finishBeyondProbabilityPct` is returned next to it for comparison (the end-of-window question itself is `workflow.run_window_fair_value`). Barrier above spot gives an up-touch, below spot a down-touch. Monitoring is continuous (every instant, not daily closes or candle highs, which touch less often); year is 365 days; `driftPct` is the annualized expected price drift, default 0. Output: touchProbabilityPct, finishBeyondProbabilityPct, direction, barrierDistancePct. Edge cases: spot, barrier and daysToExpiry (at most 3650) above zero; volatilityPct 0.01 to 1000; driftPct -1000 to 1000; barrier and spot must be within a factor of about 5e8 of each other. Not covered: a discrete-monitored barrier, knock-in or knock-out option prices, jumps, volatility that changes over time, trading costs; the probability is under a constant volatility and drift.

Theoretical European option price and Greeks (delta, gamma, theta, vega, rho) from Black-Scholes, given manual spot/strike/days-to-expiry/volatility/risk-free-rate inputs plus an optional continuous dividend yield for stocks and ETFs (the implied-volatility and option-chain tools do not take one): no live data fetch. The live variant is workflow.run_black_scholes_live, which applies when checking a real Deribit, Binance or Bybit instrument, since that variant also reports how far the instrument's actual quoted price sits from what this formula implies. Prices are USD-denominated (the universal convention); callPriceCoin/putPriceCoin additionally divide by spot to match Deribit's own coin-settled quoting convention. Assumptions: European exercise only, one flat volatility for the whole life (no smile or skew), constant rate and dividend yield, a year of 365 calendar days, theta per calendar day. Edge cases: spot, strike, daysToExpiry and volatilityPct must be above zero; riskFreeRatePct and dividendYieldPct must be between 0 and 100, so a negative rate is refused; a deep out-of-the-money option returns a price and Greeks of exactly 0, and a very low volatility or very short expiry gives a very large gamma and theta, not an error. Not covered: early exercise (use workflow.run_american_option), discrete dividends, negative rates, transaction costs, taxes, margin, and Greeks adjusted for coin-settled (inverse) options: Greeks are standard USD Black-Scholes Greeks. Use when user asks "what should this option be worth at X% IV?" or wants raw Greeks for a hypothetical. Returns: callPriceUsd/putPriceUsd, callPriceCoin/putPriceCoin, deltaCall/deltaPut, gamma, vegaPerPct (per 1 vol point), thetaCallPerDay/thetaPutPerDay, rhoCallPerPct/rhoPutPerPct (per 1 rate point).

Black-Scholes theoretical price and Greeks for a REAL, live option instrument on Deribit (BTC/ETH, coin-settled) Binance (BTC, ETH, XAU, XAG, USDT-settled) or Bybit (BTC, ETH, USDT-settled): pulls that instrument's own spot, strike, days to expiry, and implied volatility from the venue, then reports how far the venue's actual quoted mark price sits from what Black-Scholes implies at that IV (priceDiscrepancyPct). This is the trust-check tool: "is this exchange's quoted price consistent with its own volatility assumption?", not an estimate, a live formula cross-check. Edge cases: European Black-Scholes on the venue mark IV with one flat volatility; an expired instrument, a missing or zero mark IV, an invalid underlying price or a mark price of 0 returns available false with the reason, never a number (every numeric field is then null); riskFreeRatePct 0 to 100 applies to Deribit only (Binance states its own rate, Bybit prices off a forward with none). Not covered: early exercise, discrete dividends, skew, bid-ask spread and Greeks adjusted for coin settlement. Use when user gives a specific instrument name (e.g. "BTC-27FEB27-90000-C" on Deribit, "BTC-261225-90000-C" on Binance, "BTC-25DEC26-90000-C-USDT" on Bybit) and asks "is this option fairly priced?" or "what are the Greeks on this contract?". Returns everything workflow.run_black_scholes does, plus instrumentName, exchange, premiumCurrency (BTC/ETH for Deribit, USDT for Binance and Bybit), optionType, markPrice, markIvPct, bsPrice, priceDiscrepancyPct, available (false + error if the instrument name doesn't resolve, the contract has expired or has no IV quote, a Binance contract states no usable risk-free rate (missing or outside -100 to 100%), or a Binance or Bybit market is not trading; then do not use any result field, they are null; read available first). For Deribit also currency, deribitMarkPriceCoin, deribitMarkIvPct, bsPriceCoin; for Binance and Bybit those and the coin-quoted callPriceCoin/putPriceCoin are null (prices are in USDT per unit, delta, gamma, vega, theta and rho are the standard USD ones for both). A contract whose mark is only a cent or two can show a large priceDiscrepancyPct; read the absolute gap there. The rate Binance states can be negative; it is returned as riskFreeRatePct, and workflow.run_black_scholes accepts 0 to 100 only, so a negative one cannot be fed back into it. Bybit prices off the forward of the expiry and states no rate: for Bybit `spot` is that forward (indexPrice is the venue index when it quotes one), riskFreeRatePct is 0, delta and gamma are per unit of the forward, and rhoCallPerPct/rhoPutPerPct are null for Bybit only (there is no rate to differentiate), the one field of workflow.run_black_scholes it does not return as a number.

Price of a plain fixed-rate bond on a coupon date, with Macaulay duration, modified duration, convexity and DV01. Price = sum of the coupons and the face value discounted at the yield per period (yield / frequency), clean price, no accrued interest, so years x frequency must be a whole number of coupon periods. The yield is the nominal yearly yield to maturity compounded frequency times a year (the bond-market convention). Durations are in years, convexity in years squared. DV01 is the price fall for one basis point of yield, a positive number, the slope at the current yield and not a repricing. It does not include credit risk, call features, taxes or the day-count of a real settlement date. Edge cases: faceValue above zero and at most 1e12 (default 1000); couponRate 0 to 1 as a fraction; yieldRate -1 to 100 with the rate per period above -100%; years above zero and at most 100; frequency a whole number 1 to 12 (default 2); years times frequency must be a whole number of coupon periods. Not covered: accrued interest and a settlement date between coupons, credit risk, call and put features, floating coupons, taxes, and the day-count convention. Use when user asks "what is a 5-year 5% coupon bond worth at a 6% yield?" or "what is the duration and DV01 of this bond?". Returns: price, pricePctOfFace, status (premium, par, discount), pvOfCoupons, pvOfFace, couponPerPeriod, periods, yieldPerPeriod, currentYield, macaulayDuration, modifiedDuration, convexity, dv01.

Pump.fun-style bonding curve calculator: exact tokens received for a buy, price impact, and graduation progress. Pure constant-product math (Uniswap V2 style) using pump.fun's official virtual-reserve constants: no live lookup needed, works for any token still on the curve (not yet graduated to a real AMM pool). Edge cases: solRaisedSoFar from 0 up to the graduation amount (a graduated token is out of range); solToSpend above zero. Pure constant-product math with pump.fun virtual-reserve constants, no live lookup. Not covered: the pump.fun trading fee unless stated in the result, slippage from other buyers landing first, tokens that already graduated to a real pool, and other launchpads with a different curve. Use when user asks "how many tokens do I get buying X SOL on this curve?" or "will this buy graduate the token?". Returns: tokensOut, priceImpactPct, progressPctBefore/After, willGraduate, partialFill (true if the buy exceeds remaining curve capacity).

Calculate the break-even exit price that covers all trading fees: this alone, nothing else. Edge cases: entryPrice and sizeBase above zero; feeOpenPct and feeClosePct fractions from 0 to 0.05 (defaults 0.0002 and 0.0005). Fees only. Not covered: funding (use workflow.run_funding_breakeven), slippage and spread. Use when user asks only "what price do I need to just break even?" and nothing more. If the user also gave a stop/target or wants a full trade-safety check, use workflow.run_risk_reward or workflow.run_pre_trade_check instead; both already include this breakeven figure plus more. Returns: breakevenPrice, totalFees.

Market Profile breakout acceptance: did price accept (hold) beyond the value area / range, or reject back inside (fakeout)? Optional buy/sell delta. Use for "did the break above VAH get accepted?". Returns: state, accepted (boolean), direction, confidence, key_levels (VAH/VAL/VPOC), scenario_framing, invalidation level. Candles come from the venue when candles[] is omitted (past sessions are cached, so repeats are fast); supplying candles[] makes the run network-free and reproducible. session_date must be a completed UTC session, before today; a session with no candles returns an error. Edge cases: instrument non-empty and venue binance or bybit; session_date is a completed UTC session before today; timeframe 1m, 5m, 15m or 30m (default 15m); value_area_rule 0.5 to 0.9 (default 0.70); supplied candles must each have high at or above low, open and close, low at or below them, and volume 0 or more; a session with no candles is an error. include_delta true or false (default true). Not covered: order flow beyond the candles given, other venues, and any statement about what price will do; the output describes the session and is not a signal.

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. Edge cases: beginningValue and endingValue above zero (a start or end of zero or below has no growth rate); years above zero and at most 1000, a fraction of a year is fine. Not covered: contributions or withdrawals in between (that is not CAGR), the path and volatility between the two dates, and any forecast; CAGR smooths a bumpy path into one rate. 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).

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. Edge cases: notional and hold_days above zero; funding_rate_long and funding_rate_short are in PERCENT per interval (0.01 means 0.01%), either sign; transfer_fee_pct 0 or more, one way (default 0.1); interval_hours 0.25 to 24 (default 8), one interval for both legs. Not covered: price divergence between the two venues, liquidation of either leg, margin needed on both venues, rates that change during the hold, and withdrawal limits; the result assumes the rates stay as given. 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).

Cash-secured put on a US stock or ETF, in US dollars with the standard 100-share contract (NOT Deribit and not coin-settled): you sell puts and hold the cash to buy the shares if they are assigned. Returns the premium income, the cash held as collateral (strike x 100 x contracts), the return for the period (premium / collateral) and the simple annualized return by days to expiry (365-day year, not compounded), the effective buy price if assigned (strike minus premium, which is also the breakeven), the net cost of the shares if assigned, the maximum profit (the premium), the maximum loss (shares to zero) and the dollars lost per $1 the price falls below the breakeven. Optional spotPrice adds the discount to buying the shares now and the strike distance from the spot; optional scenarioPrice adds the P&L at expiry at that price, whether the put is assigned, and the same price move compared with buying the shares now at spotPrice. A scenario price exactly at the strike counts as not assigned (the P&L is the same either way). A premium at or above the strike is refused. The premium is the one you type (per share, as quoted); commissions, early assignment, taxes, dividends and interest on the cash are not modelled. Edge cases: strike above zero; premium 0 or more and below the strike; contracts a whole number from 1 to 1,000,000; daysToExpiry 1 to 3650; spotPrice above zero and scenarioPrice 0 or more when given. Not covered: a fractional contract, and (already stated) commissions, early assignment, taxes, dividends and interest on the cash. Use when the user asks what selling a cash-secured put pays, what price they would effectively buy at, or whether it beats buying the stock now. Prices are computed, nothing is fetched.

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. Edge cases: x and y each at least 20 values and the same length, one observation per date (otherwise an error); constant residuals (zero variance) are an error; the test is one direction (y regressed on x), Engle-Granger. Not covered: more than two series (Johansen), structural breaks, a time trend in the regression, half-life of the spread, transaction costs, and any claim that the relation continues. 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).

Project capital growth from reinvesting perpetual futures funding income (compounding carry). Edge cases: initialCapital above zero; fundingRatePct in percent per interval (0.01 is 0.01%), either sign; intervalHours a whole number that divides 24 (1, 2, 3, 4, 6, 8, 12 or 24, default 8); durationDays above zero and at most 3650; reinvestPct 0 to 100 (default 100); a result too large to represent is an error. Assumes the rate stays constant. Not covered: a changing rate, fees, taxes, and the capital limits a venue may set. 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.

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. Edge cases: spotEntry, strike, daysToExpiry, quantity and scenarioPrice above zero; premiumCoin above zero and at most 0.999 (Deribit form). The annualized yield is simple, 365 / daysToExpiry, not compounded. Not covered: early assignment, margin, fees, taxes, dividends, rolling, and the P&L before expiry. 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). With exchange "binance" (USDT-settled, premiumUsdt) the yield is premium divided by spotEntry (one unit is not a fraction of a coin), annualized by 365/daysToExpiry, and it returns: staticYieldPct, annualizedYieldPct, valueAtScenarioUsdt (covered call = min(S, K) + premium per unit), breakevenPrice (covered_call: spotEntry - premium, null when the cap sits below the cost), capValuePerUnitUsdt (covered_call: strike + premium), floorValuePerUnitUsdt (protective_put: strike - premium), vsHoldingUsdt; USDT is not converted to USD.

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. Edge cases: 2 to 5 quotes or 2 to 5 manualProbabilitiesPct (each 0.01 to 99.99); stakeUsd above zero; feePctPerLeg 0 to 0.2 (default 0). The No price of a venue is taken as 1 minus its Yes price. A gap that fees erase is reported as isArbitrage false. Not covered: the identifiers being the same bet and resolving the same way (you confirm that), order book depth and slippage, withdrawal and deposit costs, settlement-rule differences, and capital lock-up until resolution. 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.

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. Edge cases: buyPrice and sellPrice above zero; give exactly one of investment (above zero, buy fee included) or quantity (above zero); buyFeePct and sellFeePct are fractions from 0 to 0.05 (default 0); holdingDays optional, annualized return only from 30 days. Spot only. Not covered: taxes, withdrawal and network fees, slippage, price moves in the quote currency, and leveraged positions (use 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).

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. Edge cases: 2 to 20 fills (size also accepted as quantity), each price and size above zero; fee_open_pct and fee_close_pct are fractions from 0 to 0.05 (defaults 0.0002 and 0.0005); every fill is on the same side and the same contract type. Not covered: fills at different times with different fees, partial closes, funding paid while the position was open, and liquidation (use workflow.run_liquidation_safety). 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.

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? Edge cases: returns at least 3; give either trial_sharpes (at least 2 values, per period; identical values are an error) or n_trials (a whole number from 2 to 1e9); avg_correlation 0 to below 1 (default 0) works only with n_trials; null_mean works only with trial_sharpes; an effective trial count of 1 or less is an error. Not covered: the real number of trials you ran if you do not state it (the result is only as honest as n_trials), multiple testing across strategies you did not count, and out-of-sample proof. 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.

Event study with a placebo: is the average return after your events (a listing, an unlock, a signal firing) different from the average return of the same window started on random non-event dates? Give event_returns and placebo_returns in the same units; optional event_tickers and placebo_tickers (one per return) cluster the standard error by ticker, because events on one coin are not independent draws. Returns the effect (event mean minus placebo mean), Welch t-test, permutation p-value (exact when the number of splits is small, otherwise seeded random shuffles; two-sided as scipy.stats.permutation_test defines it), the cluster-robust t and p (statsmodels cluster covariance, t with clusters-1 degrees of freedom), the single event carrying most of the effect with the effect once it is dropped, honesty flags (few events, few clusters, one event dominates, sign flips without it, clustering changes the verdict) and a verdict that is distinguishable_from_placebo, not_distinguishable or fragile. It tests a difference you hand it; it does not pick dates, fetch prices or correct for look-ahead. Edge cases: event_returns and placebo_returns each 2 to 5000 finite values; event_tickers and placebo_tickers, if given, one per return, 1 to 32 characters; n_permutations a whole number 1000 to 100,000 (default 10,000) and permutations times events at most 50,000,000; alpha strictly between 0 and 0.5 (default 0.05); seed a whole number (same seed, same result); two constant samples are an error. Not covered: choosing the event window or the placebo set (the result is only as good as that choice), overlapping events, clustering in time, and causality. Use when user asks "is this effect real or noise", "does my signal beat random dates" or "run an event study with a placebo". Without at least two ticker clusters the verdict is never distinguishable_from_placebo, because there is no clustered test to confirm it.

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. Edge cases: at least 100 finite returns; threshold_percentile strictly between 0 and 100 (default 90); confidence strictly between 0 and 1 (default 0.99); at least 10 returns beyond the threshold, otherwise an error; if the tail fit does not converge, the call is an error suggesting another threshold. Not covered: a tail model for gains, time-varying volatility, the choice of the best threshold (try several), and the risk beyond what the sample has seen. 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).

Calculate the exact exit price needed to hit a target PnL or ROE percentage. Edge cases: entryPrice, leverage and sizeBase above zero; targetMode pnl or roe, targetValue any number; fees 0 to 0.05 (defaults 0.0002 and 0.0005); a target that cannot be reached from this position is an error. Not covered: funding, slippage, liquidation before the target, and the chance that price gets there. 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.

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. Edge cases: high and low above zero and finite, high above low (equal or reversed is an error); direction is up or down. Not covered: choosing the swing points, confluence with other levels, and any statement about where price will turn; the levels are arithmetic.

Size-weighted (arithmetic) average entry price across multiple forex fills. Edge cases: at least 1 fill; every price and units above zero; pair is BASE/QUOTE with two different ISO 4217 codes (a metal such as XAU/USD is accepted here because no pip is needed). The average is weighted by units, not by cash. Not covered: swap, commission, spread, fills in different pairs, and closing fills (buys only). Use when user asks "what's my average entry after these fills?". Returns: totalUnits, totalCost, avgEntry.

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. Edge cases: entryPrice above zero; spreadPips and commissionPerLotRoundTrip zero or more (commission default 0, in the quote currency per 100,000 units round trip); The pair is BASE/QUOTE with two different ISO 4217 currency codes, in any letter case; crypto tickers and precious metals (XAU, XAG, XPT, XPD) are refused. A pip is 0.01 for a pair quoted in JPY and 0.0001 for every other pair, and a standard lot is 100,000 units. Not covered: swap, slippage, requotes, account-currency conversion, and a commission quoted per side or per million. Use when user asks "where's my true breakeven after spread and commission?". Returns: pipSize, commissionPips, totalCostPips, breakevenPrice.

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. Edge cases: each series needs at least 5 positive prices, and both series must be the same length with one price per matching date (a different length is an error); a series with no movement (zero return variance) is an error because correlation is undefined. Not covered: lagged correlation, rolling windows, significance tests and confidence intervals; 4 returns is the mathematical minimum, not a reliable sample. Use when user already has two price series and wants their statistical relationship. Returns: n, correlation (-1 to 1), hedgeRatio.

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." Edge cases: days is a whole number from 14 to 365 (default 30) of calendar days, so fewer trading days are used; both pairs must be BASE/QUOTE of two different ISO 4217 codes; dates present in only one series are dropped; too few overlapping dates, or a flat series, gives available false. Daily ECB reference rates only, no intraday data. Not covered: lagged correlation, rolling windows and significance tests. 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.

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. Edge cases: rate above zero; amount may be zero or negative (it is converted as given); the tool takes the amount and the rate only, no currency codes. Not covered: bank or broker markups, fees, rounding rules of a particular provider, and the direction of the rate (you must supply the rate that applies from the first to the second currency). Use when user already knows the exact rate they want applied. Returns: converted.

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). Edge cases: amount may be zero or negative (converted as given); from and to are ISO 4217 codes; the same currency on both sides returns the amount with source identity; no rate found gives available false and no figure. The rate is a TrueFX tick or a daily ECB reference rate, not what a bank or broker would give you. Not covered: markups, fees and rounding rules of a provider. 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.

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. Edge cases: equity above zero, usedMargin zero or more; usedMargin of 0 returns marginLevelPct null (no open position), not a large number; equity below used margin gives a level under 100. Not covered: a broker margin-call or stop-out threshold (they differ by broker), pending orders, hedged-position margin offsets, and swap or commission not yet charged. Use when user asks "how close am I to a margin call?" or "what's my free margin?". Returns: freeMargin, marginLevelPct.

Notional and margin required for a forex position, in the pair's own quote currency: no live FX rate needed. The live variant is workflow.run_forex_margin_required_live, which applies when the account currency differs from the pair's quote currency. Edge cases: units, price and leverage above zero (leverage 50 means 50:1); the pair is BASE/QUOTE with two different ISO 4217 codes (no pip is needed, so a metal pair is accepted). Margin is notional / leverage in the quote currency. Not covered: broker margin tiers, per-instrument leverage caps, hedge offsets, and conversion to the account currency (use workflow.run_forex_margin_required_live). Use when user asks "how much margin do I need for X lots of EUR/USD at 50:1?". Returns: notionalQuote, marginQuote, base, quote.

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). Edge cases: same input rules as workflow.run_forex_margin_required; when no rate is found for the account currency, available is false and no figure is returned. The rate is a TrueFX tick or a daily ECB reference rate, not a dealer quote. Not covered: broker margin tiers and margin offsets on hedged positions. 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.

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. Edge cases: units above zero; The pair is BASE/QUOTE with two different ISO 4217 currency codes, in any letter case; crypto tickers and precious metals (XAU, XAG, XPT, XPD) are refused. A pip is 0.01 for a pair quoted in JPY and 0.0001 for every other pair, and a standard lot is 100,000 units. The value comes back in the pair quote currency. Not covered: brokers that use a fractional pip (pipette), non-standard lot sizes, metals and indices, and the account-currency conversion (use workflow.run_forex_pip_value_live). Use when user asks "what's 1 pip worth on X lots of EUR/USD?". Returns: pipSize, pipValueQuote, base, quote.

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. Edge cases: same input rules as workflow.run_forex_pip_value; when no rate is found for the account currency, available is false and no figure is returned. The rate is a TrueFX tick or a daily ECB reference rate, not a dealer quote. Not covered: broker markups and fractional pips. 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.

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. Edge cases: entryPrice, exitPrice and units above zero; The pair is BASE/QUOTE with two different ISO 4217 currency codes, in any letter case; crypto tickers and precious metals (XAU, XAG, XPT, XPD) are refused. A pip is 0.01 for a pair quoted in JPY and 0.0001 for every other pair, and a standard lot is 100,000 units. The result is in the quote currency; a short position gains when the price falls. Not covered: spread, commission, swap, slippage and account-currency conversion. 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.

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. Edge cases: entryPrice, stopPrice and riskAmount above zero; a stop equal to the entry gives available false (no risk distance); The pair is BASE/QUOTE with two different ISO 4217 currency codes, in any letter case; crypto tickers and precious metals (XAU, XAG, XPT, XPD) are refused. A pip is 0.01 for a pair quoted in JPY and 0.0001 for every other pair, and a standard lot is 100,000 units. Units are not rounded to a broker lot step. Not covered: spread and slippage on the stop, commission, margin limits, and a minimum or step lot size of your 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.

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. Edge cases: entryPrice, stopPrice and targetPrice above zero; The pair is BASE/QUOTE with two different ISO 4217 currency codes, in any letter case; crypto tickers and precious metals (XAU, XAG, XPT, XPD) are refused. A pip is 0.01 for a pair quoted in JPY and 0.0001 for every other pair, and a standard lot is 100,000 units. A stop equal to entry or a stop or target on the wrong side of entry for the chosen side gives ratio null (check validSetup). Not covered: spread, commission, swap, slippage, and the probability that the target is hit. Use when user asks "what's my risk/reward on this setup?". Returns: riskPips, rewardPips, validSetup, ratio.

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. Edge cases: entryPrice and units above zero; deltasPips is a list of at least one signed number of pips (positive means the price rose, whatever the side); a move that takes the exit price to zero or below is not rejected, read exitPrice; The pair is BASE/QUOTE with two different ISO 4217 currency codes, in any letter case; crypto tickers and precious metals (XAU, XAG, XPT, XPD) are refused. A pip is 0.01 for a pair quoted in JPY and 0.0001 for every other pair, and a standard lot is 100,000 units. Not covered: spread, commission, swap, slippage and account-currency conversion. Use when user asks "what if price moves X pips in either direction?". Returns: scenarios[] (deltaPips, exitPrice, pnlQuote).

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. Edge cases: units above zero; nights a whole number above zero; swapPerLotPerNight any number, negative is a cost, positive a credit, quoted per 100,000 units in the quote currency; The pair is BASE/QUOTE with two different ISO 4217 currency codes, in any letter case; crypto tickers and precious metals (XAU, XAG, XPT, XPD) are refused. Not covered: the triple swap on Wednesday (count it in nights yourself), changing swap rates, and account-currency conversion (use workflow.run_forex_swap_cost_live). Use when user asks "how much will holding this position overnight cost me?". Returns: lots, totalSwapQuote, base, quote.

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. Edge cases: same input rules as workflow.run_forex_swap_cost (nights a whole number, swap any sign); when no rate is found for the account currency, available is false and no figure is returned. Not covered: the triple swap on Wednesday and swap rates that change during the hold. 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.

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. Edge cases: positionSize and durationDays above zero; longFundingRate and shortFundingRate in percent per interval (0.01 is 0.01%), either sign; transferFeePct 0 or more (default 0.1); intervalHours 0.25 to 24 (default 8). Not covered: price divergence between the venues, liquidation of either leg, margin on both venues, a rate that changes during the hold, and trading fees. Use when user asks "is this funding arb worth it?" or "how many days to break even on transfer fees?". Returns: netProfitUsdt, annualizedYieldPct, breakevenDays.

Price move needed to cover funding cost + fees over a holding period. Edge cases: entry_price, size and hold_hours above zero; funding_rate is a decimal per funding interval (0.0001 is 0.01%), either sign; funding_interval_hours 0.25 to 24 (default 8); fees are fractions from 0 to 0.05. If carry cost exceeds what any price move can offset, the call is an error. Not covered: a funding rate that changes during the hold, mark versus last price, and slippage. 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.

Calculate the total funding cost (or income) for holding a perpetual futures position. Edge cases: sizeBase, entryPrice and days above zero; fundingRate a fraction per interval (0.0001 is 0.01%), either sign; intervalHours 0.25 to 24 (default 8); if funding exceeds the position notional there is no finite price shift that offsets it, which is an error. Not covered: a funding rate that changes during the hold, and price moves. 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).

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). Edge cases: annualRate from -1 to 100 as a fraction (0.05 is 5%) with the rate per period above -100%; years 0 to 1000; periodsPerYear a whole number 1 to 365 (default 1); paymentTiming end (default) or begin; when a payment is given, years times periodsPerYear must be a whole number. A result too large to represent is an error. Not covered: a rate that changes over time, uneven or growing contributions, inflation, taxes and fees, and any guarantee that the rate is earned. 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.

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. Edge cases: at least 50 returns; a flat series is an error; non-finite values are refused. Output is per period of the input (no annualization). Not covered: asymmetric models (GJR, EGARCH), fat-tailed errors (the fit is Gaussian maximum likelihood), multi-step forecasts, and a guarantee that the optimizer finds the global maximum. 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.

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)? Edge cases: at least 32 values; min_window a whole number of at least 4 (default 8); a series too short to give at least 3 window sizes at that min_window is an error. Takes returns, not price levels. Not covered: confidence intervals for H, bias correction for short samples, other estimators (DFA, wavelets). R/S estimates are noisy on short series and H near 0.5 is not a verdict. 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.

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). Edge cases: entryPrice and currentPrice above zero; concentrated mode needs both lowerPrice and upperPrice with lowerPrice below entryPrice and entryPrice below upperPrice; depositValueUsd above zero and feesEarnedUsd 0 or more are optional, and dollar figures are null without a deposit. Not covered: price moves inside the period, rebalancing, gas, tax, and a quote token whose own USD price moves (dollar figures assume it is stable). 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).

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. Edge cases: same input rules as workflow.run_impermanent_loss, except currentPrice is derived from the live USD prices of the two tokens (each on solana, ethereum, base, bsc, arbitrum or polygon); if either price cannot be read, routable is false with an error and no figure is returned; entryPrice stays manual. Not covered: price moves inside the period, rebalancing, gas, tax, and thinly traded tokens whose quoted price is unreliable. 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).

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. Edge cases: spot, strike, daysToExpiry and targetPriceUsd above zero; riskFreeRatePct 0 to 100; the search range is 0.01 to 1000 volatility points; a price outside the no-arbitrage bounds returns converged false with an error, not a number. Not covered: American exercise (a stock option price may imply a different volatility), dividends, a volatility smile, bid-ask spreads (one price in), coin-settled prices (convert to USD first). 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.

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. Edge cases: 2 to 1000 finite cash flows with at least one inflow and one outflow, equal periods, first flow at time 0; periodsPerYear a whole number 1 to 365, optional. The rate is per period. Several sign changes can give several rates or none, then irr is null (see reason). Not covered: flows at irregular dates (that is XIRR), reinvestment at a different rate (that is MIRR), and a rate outside -99% to +9,900% per period. 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.

Kelly growth-security frontier (MacLean, Ziemba & Blazenko 1992): for a strategy compounding at a fraction lambda of full Kelly, the probability wealth ever falls to a fraction alpha of its starting value is P = alpha^(2/lambda-1). Provide either lambda_fraction (to compute that probability) or max_probability (to solve for the largest lambda that keeps the ruin probability at or below it). Edge cases: alpha strictly between 0 and 1; give exactly one of lambda_fraction (above 0) or max_probability (strictly between 0 and 1), not both and not neither. Not covered: the edge of a real strategy and its estimation error, transaction costs, discrete bets, and the probability of falling to alpha at a fixed date (the probability is of ever falling to it). Use when user asks "if I bet half-Kelly, what's my chance of ever losing half my bankroll?" or "what fraction of Kelly keeps my chance of a 50% drawdown under 5%?". Valid lambda range is (0, 2]; beyond 2 the probability is certain (1), not the raw formula value. Returns: probability, lambda_fraction (echoed or solved).

Largest equal leg, in whole contracts, for a scale-in ladder of D legs (linear perpetuals, cross margin). Edge cases: linear perpetuals and cross margin only; legs, step or steps, equity and leverage must describe a real ladder, and an unknown symbol or an unreachable exchange gives available false. Result is capped at 10,000,000 contracts. Not covered: isolated margin, inverse contracts, fees, funding, slippage between legs, and the exchange own liquidation engine; liq_buffer is our model of cross margin. Use when user asks "how many contracts per leg can I put on a ladder of 8 legs at 3x with this equity?". Legs chain from currentPrice: each is `step` further against the position (a short ladder climbs, a long ladder falls); an existing position (existingCt) is leg 1, the other legs-1 are new; oppositeCt is a hedge on the other side (adds to exposure, its PnL moves with price). equity is the account equity measured at currentPrice. mode "leverage" (default): after every leg, gross contracts x ctSize x price <= leverage x equity at that price (equity includes the loss of every position at that price); liquidation does not take part; fees are not in equity. mode "liq_buffer": the cross-margin liquidation price of the full ladder, from the exchange's live maintenance-margin tiers (exchange and symbol, same tables as workflow.run_liquidation_live), must stay beyond the last leg by at least bufferPct (0.3 for 30%); on OKX pass liqFeeRate (the taker fee rate). Mode liq_buffer does not apply the leverage cap (exposureOverEquityAtLastLeg shows the result) and respects the exchange's largest position (checked at each leg's own price after it fills, not at a later mark); it is our model of cross margin (the opposite side is a fixed oppositeMaintenanceMargin), not the exchange's engine, and the exchange may report no liquidation price for a hedged account. It looks for liquidation in the ladder's adverse direction only: when none exists (noLiquidationInLadderDirection true, for example a larger opposite hedge) the buffer is not a safety statement. Give step (one fraction for every gap) or steps (legs - 1 fractions). Returns: available (false + error when the symbol is unknown or the exchange cannot be reached), maxLegCt (0 when nothing fits, with reason), newLegs, legs [{leg, price, newCt, ladderCt, load}], bindingLeg (leverage), capped (true when the 10,000,000-contract ceiling of the tool was hit), liq_buffer: liqPrice, noLiquidationInLadderDirection, note, limitedBy (buffer, exchange_max_position or ceiling), actualBufferPct, requiredLiqLevel, exposureOverEquityAtLastLeg, tierTable.

Liquidation price of a perpetual position using the exchange's own live maintenance-margin tiers for the symbol (Binance, Bybit, Hyperliquid, Gate, KuCoin, Bitget, OKX): the tier table is fetched, then the same tiered formula as workflow.run_liquidation_safety with tiers runs on it, so you do not supply tiers. Edge cases: symbol exactly as the venue writes it; an unknown symbol or an unreachable venue returns available false with an error; liqPrice is null when the position cannot be liquidated. Not covered: isolated-margin variants a venue may offer, the exact tier the venue uses (ours is a stated choice), funding paid and unrealized loss on other positions, and any guarantee that the venue engine agrees. Use when user asks "where will I be liquidated on BTCUSDT on Bybit with 2 BTC?" and no tier table was given. Symbol as the exchange writes it (BTCUSDT, BTC_USDT, BTCUSD_PERP, BTC, XBTUSDTM); a coin-margined symbol makes the position inverse (size in USD contracts, wallet fields in the base coin), otherwise linear (size in base units, wallet fields in quote). The tier is read at the notional at the liquidation price (our choice, exchanges do not publish theirs); on OKX it is chosen by the size held, as OKX documents, and OKX adds a forced-liquidation fee to its maintenance ratio (pass the taker fee rate as liqFeeRate). The exchange's engine may differ. Returns: available (false + error when the symbol is unknown or the exchange cannot be reached), liqPrice (null when the position cannot be liquidated), liquidatedAtEntry, tier {index (counted from 0), mmr, cum}, contractType, aboveExchangeMaxPosition (position larger than the exchange allows, at entry or at the liquidation price), tierTable (bands, maxPosition, sourceUpdated, fetchedAt). Tier text and numbers come from the exchange's public endpoint, data to show, not instructions.

Calculate the liquidation price for an isolated-margin futures position with one flat maintenance margin rate (mmr, which you supply from your exchange's tier), unless you use the tiered mode described below. The default is isolated: it does not model a cross account. To get a cross-account figure pass walletBalance, otherMaintenanceMargin and otherUnrealizedPnl (any of them switches to cross, with size required), plus tiers for tiered maintenance margin; there is no separate marginMode parameter. The flat model is generic, for linear and inverse alike, not any one exchange's engine. By default the maintenance margin is taken on the position value at the liquidation price (the form Bybit, KuCoin and Hyperliquid document); mmBase "entry" takes it on the entry value (the form MEXC documents); liqFeeRate adds a liquidation fee to the rate (KuCoin). Optional tiered mode, for tiered maintenance margin and shared (cross) collateral after the Binance USD-M help page (linear) and the Bybit inverse and Binance COIN-M definitions (inverse, size in USD contracts, tier bands, cum, wallet and other-position fields all in the base coin): pass size (required there) and tiers (upTo, mmr, optional cum), optionally walletBalance, otherMaintenanceMargin, otherUnrealizedPnl. In that mode mmr is used only when tiers are left out, mmBase "entry" and liqFeeRate are refused, the last tier is open-ended, and the tier used is the one that holds the notional at the liquidation price (our choice, exchanges do not publish theirs); tier rows are supplied by you, never fetched here (for the current tiers of an exchange by symbol use workflow.run_liquidation_live), and the result then also carries tier {index, mmr, cum}. Without those fields it is the flat model: no tiers and no shared collateral, so it can differ from an exchange's own figure. Edge cases: entryPrice and leverage above zero; mmr 0 to 0.2 (default 0.005); liqFeeRate 0 to 0.05 (default 0, refused in tiered mode); tiered mode needs size, 1 to 50 tiers ascending by upTo, mmr 0 to 0.5 never lower than the previous tier, only the last tier may leave out upTo, and a cum that disagrees with the tier rates is an error; walletBalance above zero, otherOpenMaintenanceMargin 0 or more. Not covered: auto-deleveraging, partial liquidation, mark price versus last price, funding paid while open, and the exchange own engine, which may differ. Use when user asks "where will I get liquidated?" or "how close is my liq price?". Returns: liqPrice (the price). liqPrice is null when the position cannot be liquidated: an inverse short whose margin covers any price rise (at 1x or less with the default mmBase; with mmBase "entry" only a little below 1x), or whose price would be more than 1e9 times the entry. Check for null before doing arithmetic on it. When mmr plus liqFeeRate is at least 1/leverage the position is already at or below its maintenance margin at entry: liqPrice is the entry price and liquidatedAtEntry is true.

Compares two tokens' live market caps (Solana or any of 5 EVM chains; the two tokens can be on different chains) and projects what an investment would be worth if the first token's market cap matched the second's. Narrative-agnostic ("if X reaches Y's market cap"): works for any token pair, not tied to one hype cycle or one chain. A snapshot ratio, not a forecast: assumes fixed supply on both sides. Edge cases: investmentUsd above zero; each token is a chain (solana, ethereum, base, bsc, arbitrum or polygon, default solana) plus an address; a token whose market cap cannot be read returns comparable false with an error. The projection is arithmetic: price times the ratio of market caps. Not covered: supply changes, dilution, liquidity to actually sell at that price, a forecast that the cap will be reached, and tokens whose market cap is self-reported. Use when user asks "what if this token reaches [other token]'s market cap?". Returns: multiplier, projectedValueUsd, projectedPriceUsd, profitUsd, comparable (false + error if either market cap can't be resolved).

Reads Kalshi's full live BTC or ETH year-end price ladder (a set of mutually-exclusive prediction markets covering the whole price range) and reports what the market itself implies: the median (50th-percentile) price bucket, the single most-likely (mode) bucket, and the probability of ending the year at or above any real bucket boundary. Deliberately does not compute an expected value or interpolate inside a bucket: the top/bottom buckets are open-ended, so any point estimate there would need an invented assumption; every number this tool returns traces back to one live, sourced price. Edge cases: coin BTC or ETH (default BTC); thresholdUsd above zero, optional, and it snaps to the nearest real bucket boundary at or below it. The ladder is read live from Kalshi only; when it is unavailable or incomplete the call returns available false with the reason. Not covered: an expected value or a price inside a bucket (the end buckets are open-ended), other venues, other horizons than the year-end ladder, and fees. Use when user asks "what does the market think BTC will be worth by year end?" or "what are the odds ETH ends the year above $X?". Returns: buckets[] (label, floor, cap, probabilityPct), medianBucketLabel, modeBucketLabel, vigPct, probabilityAtOrAbovePct + snappedThresholdUsd (only when thresholdUsd is supplied). If available is false, do not use any result field (computed figures and any verdict are null or empty), so read available first.

Calculate the maximum leverage that keeps a position within a drawdown limit, from account size, max acceptable drawdown, and asset daily volatility. Edge cases: accountSize and volatilityPct above zero; maxDrawdownPct above 0 and at most 100; mmr 0 to 0.1 (default 0.005). A planning figure from the numbers you give, not a limit set by an exchange. Not covered: gaps and fat-tail moves beyond the volatility you state, exchange maximum leverage and tiers, funding, and fees. Use when user asks "what leverage does a 10% drawdown limit allow on BTC?" or "what leverage fits a 3% daily volatility and a 10% drawdown limit?". Returns: maxLeverage (maxDrawdownPct / (volatilityPct + mmr x 100), rounded down to 0.1, never below 1x), marginAtRisk (accountSize x maxDrawdownPct / 100, in USDT), safeMargin (USDT) and liquidationBuffer (percent). maxDrawdownPct and volatilityPct are percents (10 means 10%); mmr is a fraction (0.005 is 0.5%).

Max pain of an option expiry: the settlement price at which holders of all calls and puts together would be paid the least, from the open interest per strike (1 contract = 1 unit of the underlying). Two modes. LIVE (omit strikes): reads one expiry's open interest from Deribit (BTC, ETH; coin-settled, payouts shown in USD), Binance (BTC, ETH, XAU, XAG; USDT) or Bybit (BTC, ETH; USDT); one venue per result, venues are never merged; omit expiry to get the nearest expiry that has open interest. An expiry with no open interest yet, or where the venue leaves a contract's open interest unstated, comes back with available false and the reason, never a number. YOUR OWN DATA (pass strikes): max pain from the open interest you supply, nothing is fetched; optional spotPrice adds how far max pain sits from it. Returns maxPainStrike (the lowest if several tie; tiedStrikes lists all), the minimum and maximum total payout, total call and put open interest, the put/call open-interest ratio, and the payout at every strike (callPayoutUsd, putPayoutUsd, totalPayoutUsd). Max pain is a descriptive statistic of open positions, not a forecast of the settlement price; who holds which side, early exercise and the venue's settlement-price method are not modelled. Edge cases: your own data takes strikes (strike above zero, open interest 0 or more, finite) and an optional spotPrice, never together with exchange, underlying or expiry; ties go to the lowest strike and all tied strikes are listed. Not covered: who holds which side, hedging, early exercise and the venue settlement-price method. Use when the user asks for the max pain strike of BTC or ETH options for an expiry, or for max pain from open interest they have.

Monte Carlo simulation of a portfolio: geometric Brownian motion with a contribution (or withdrawal) at the end of every step, up to 10,000 paths (paths x steps at most 5 million), deterministic for a given seed. Returns the spread of final values (percentiles 5 to 95, mean with its standard error and the exact expected value, probability of ending below the net amount invested, probability of ending a step at or below a ruin level) and a fan of 5th, 50th and 95th percentile bands over time, instead of one number. A value that would go below zero is floored at zero. Constant return and volatility, no fees or taxes: a model of spread, not a forecast. Edge cases: initialValue 0 to 1e12 (0 needs a positive contribution); contributionPerStep -1e12 to 1e12 (negative is a withdrawal, paid at the end of each step); annualReturnPct -100 to 500; volatilityPct 0 to 500; years above 0 and at most 50; stepsPerYear a whole number 1 to 365; years times stepsPerYear a whole number of at most 18,250; paths a whole number 100 to 10,000 and paths times steps at most 5,000,000; seed a whole number (default 1, the same seed gives the same result). Not covered: fat tails and volatility clustering (returns are lognormal), taxes, inflation, fees, sequence-of-returns beyond the simulated model, and any forecast. Use when user asks "what range of outcomes can my portfolio end in", "how likely is it that I run out of money withdrawing X a month" or "simulate my savings plan".

Net present value of a list of cash flows at a discount rate per period. The first flow is at time 0 and is NOT discounted (the usual textbook NPV; a spreadsheet NPV() function discounts the first value one period, so its result is this one divided by 1 + rate). Money received is positive, money paid is negative. ratePerPeriod must match the spacing of the flows (a monthly rate for monthly flows). To find the rate that makes NPV zero use workflow.run_irr. Edge cases: ratePerPeriod strictly above -1 and at most 1e6, as a fraction per period (0.05 is 5%), not per year; 1 to 1000 cash flows, the first at time 0, all finite; money received is positive and money paid is negative. Not covered: flows at irregular dates (use equal periods), a rate that changes, taxes, inflation, and the choice of discount rate; a positive NPV is arithmetic, not a decision. Use when user asks "is this project worth doing at a 10% cost of capital?" or "what is the NPV of these cash flows?". Returns: npv, discountedFlows, pvOfInflows, pvOfOutflows, undiscountedSum, periods.

Converts one probability into decimal odds, American odds, and breakeven win rate: either from a manually supplied probability, or from one market read live from Kalshi, Polymarket, ADI Predictstreet, Limitless, or Myriad (five independent crypto-price prediction market venues, all public keyless market data). One market on one venue per call; it does not compare prices across venues (to compare the same bet on two or more venues, see workflow.run_spread_reader). When a Kalshi, Polymarket, Limitless, or Myriad source is supplied, also returns the vig (the exchange's built-in edge), computed from the market's own YES+NO prices, not estimated; ADI Predictstreet's crypto contracts currently have no live trading volume on any venue, so this returns available:false with an explanation rather than a fake price (use workflow.run_window_fair_value for a theoretical price on those instead). Edge cases: probability strictly between 0.0001 and 0.9999 (a decimal, 0.35 is 35%); give exactly one source, never none and never two; a market that cannot be read live, or a two-sided source with no usable prices, returns available false with the reason; vig is null for a manual probability. Not covered: fees and slippage, depth of the order book, matching the same bet across venues, and any claim that the probability is correct. Use when user asks "what odds does a 35% probability work out to?" or "what's the vig on this Kalshi/Polymarket/Limitless/Myriad market?". Provide exactly one of probability/kalshiTicker/polymarketSlug/adiSymbol/limitlessSlug/myriadSlug. Returns: probability, decimalOdds, americanOdds, breakevenWinRatePct, vigPct (null unless a live two-sided source was used), source (manual/kalshi/polymarket/adi/limitless/myriad), identifier, label. If available is false, do not use any result field (computed figures and any verdict are null or empty), so read available first.

Market Profile open analysis: where and how price opened vs the prior session value area. Use for "how did BTC open today?" / "what does the open imply for the session?". Returns: open_location, open_type (OD/OTD/ORR/OAIR) with description/implication, confidence, key_levels (VAH/VAL/VPOC/IB), tails (session-high/low rejection tails and single prints), scenario_framing (bullish/bearish/neutral), invalidation level. Candles come from the venue when candles[] is omitted (past sessions are cached, so repeats are fast); supplying candles[] makes the run network-free and reproducible. session_date must be a completed UTC session, before today; a session with no candles returns an error. Edge cases: instrument non-empty and venue binance or bybit; session_date is a completed UTC session before today; timeframe 1m, 5m, 15m or 30m (default 15m); value_area_rule 0.5 to 0.9 (default 0.70); supplied candles must each have high at or above low, open and close, low at or below them, and volume 0 or more; a session with no candles is an error. Not covered: order flow beyond the candles given, other venues, and any statement about what price will do; the output describes the session and is not a signal.

First and second order Greeks of a European option from Black-Scholes-Merton, manual inputs only (no live data): everything workflow.run_black_scholes returns (price, delta, gamma, vega, theta, rho) plus the higher-order Greeks vanna, vomma (volga), charm, veta, speed, zomma and color, with an optional continuous dividend yield for stocks and ETFs. Edge cases: daysToExpiry 0.001 to 36500, volatilityPct 0.01 to 1000, spot and strike above zero, riskFreeRatePct and dividendYieldPct 0 to 100; inputs so extreme that a Greek is not a finite number (a strike far from the spot for the volatility and time) are an error, not a null. Not covered: early exercise (use workflow.run_american_option), discrete dividends, a volatility smile (one flat volatility), negative rates, Greeks of coin-settled options; Greeks are USD Black-Scholes Greeks. Use when the user asks how delta changes when volatility or time moves (vanna, charm), how vega changes (vomma, veta) or how gamma changes (speed, zomma, color), or for an "option greeks calculator". Units: vannaPerVolPct = change of delta per 1 volatility point; vommaPerVolPct = change of vegaPerPct per 1 volatility point; charmCallPerDay/charmPutPerDay = change of delta when one calendar day passes; vetaPerDay = change of vegaPerPct when one calendar day passes; speedPerUsd = change of gamma per 1 unit of spot; zommaPerVolPct = change of gamma per 1 volatility point; colorPerDay = change of gamma when one calendar day passes. Time Greeks are the change as time passes (the derivative with respect to time to expiry, sign flipped); one input moves, the others stay fixed. Vanna, vomma, veta, speed, zomma and color are the same for the call and the put; charm differs by the dividend term only. A calendar day is 1/365 year.

Payoff, P&L, and breakeven price for a single-leg Deribit BTC/ETH option (long or short call/put) at a given scenario price at expiry. Deribit BTC/ETH options are coin-settled: premium, P&L, and the max profit/loss caps come back denominated in the base coin (BTC/ETH), not USD; a scenarioPnlUsd convenience field converts the coin P&L back to USD at the scenario price. Coin settlement means a long call's upside is capped (max profit = 1 − premium per unit, not unlimited) while a long put's upside is technically unbounded as price falls toward zero, the mirror image of a USD-settled option's payoff shape, not a bug. Edge cases: strike, premium, quantity and scenarioPrice above zero; a coin premium for a call must be below 1. Not covered: early exercise, margin, fees, Greeks, the probability of profit and the value before expiry; the result is the payoff at expiry at one scenario price. Use when user asks "what does my BTC call/put pay off at price X?" or "where's my breakeven on this option?". Returns: intrinsicPerUnitCoin, scenarioPnlCoin, scenarioPnlUsd, breakevenPrice, maxLossCoin/maxProfitCoin (null = unbounded), isProfitable. With exchange "binance" (USDT-settled, flat payoff, premiumUsdt instead of premiumCoin) it returns the USDT equivalents: intrinsicPerUnitUsdt, scenarioPnlUsdt, breakevenPrice (K + premium for a call, K - premium for a put), maxLossUsdt/maxProfitUsdt (null = unbounded: a long call's profit is unlimited, a long put's best case is K - premium); USDT is not converted to USD.

Profit and loss at expiry for a US-style equity, ETF or index option position built from 1 to 4 option legs, in US dollars with the standard contract multiplier of 100 shares (NOT Deribit and not coin-settled: for BTC/ETH options on Deribit use workflow.run_spread_payoff or workflow.run_options_payoff). Each leg: call or put, long or short, strike, premium per share as quoted, contracts. Optional `stock` adds long shares held with the options (covered call, protective put, collar). Prices are the ones you pass in; nothing is fetched. All legs share one expiry (a calendar spread is not computed). Returns: the strategy name derived from the legs (bull/bear call or put spread, iron condor, iron butterfly, straddle, strangle, covered call, protective put, collar, single leg, or a custom position), net debit or credit in dollars, maxProfitUsd and maxLossUsd (null = unlimited), every breakeven price per share, the P&L at each price in `scenarioPrices` and a short exact payoff curve. maxLossUsd is the worst P&L as a loss amount (negative if no price loses); maxProfitUsd is the best P&L (negative if every price loses). Edge cases: 1 to 4 legs; strike and premium up to 10,000,000, premium may be 0; contracts a whole number from 1 to 100,000; stock quantity a whole number up to 100,000,000; up to 50 scenarioPrices, each 0 to 1e9. Not covered: calendar or diagonal spreads (one expiry only), early assignment, commissions, taxes, dividends, margin, Greeks and the value before expiry.

Order-book "walk the book" impact/capacity: given order-book levels (price, size in base-asset units) and EITHER a target notional or an impact budget in bps, computes VWAP and price impact for that size, or (via bisection) the largest notional that stays inside the impact budget. Edge cases: bids and asks each at least 1 level (price, size in base units, any order); side buy or sell; give exactly one of notional_usd or impact_budget_bps, both above zero. A book too thin for the size returns book_sufficient false and no VWAP. Not covered: a book that moves while you trade, hidden liquidity, your own fees, and any depth you did not supply (capacity_is_lower_bound says when the whole supplied book fit). Use when user asks "what's my price impact if I trade $X" or "how much can I trade before impact exceeds Y bps". side="buy" walks the asks, side="sell" walks the bids; impact is measured from the book's own mid ((best_bid+best_ask)/2) and is always a positive "cost in bps" number regardless of side. Returns: mid_price, spread_bps, vwap, impact_bps - both null when EITHER the loaded book doesn't cover the requested notional (book_sufficient=false flags this specific case) OR the notional involved is ~0 (book_sufficient stays true then; happens for a near-zero notional_usd, or in capacity mode when even an infinitesimal trade already exceeds impact_budget_bps, in which case max_notional itself resolves to 0) - and in capacity mode, max_notional plus capacity_is_lower_bound (true if the ENTIRE supplied book was consumed within budget, meaning true market capacity may exceed what was supplied - this tool only sees the levels given to it).

Calculate net PnL, ROE, fees and gross profit/loss for a futures trade. Edge cases: entryPrice, exitPrice and size above zero; feeOpenPct and feeClosePct optional fractions from 0 to 0.05 (0.0002 is 0.02%). For inverse contracts size is USD contracts and results are in the base coin. Not covered: funding payments, slippage, liquidation before the exit price is reached, and taxes. Use when user asks "what's my profit/loss on this trade?" Returns: grossPnl, fees, netPnl, netPnlUsdt, roe (%), maxLossBound (only non-null for an inverse/coin-margined short: the finite ceiling on net coin-denominated loss as price rises without limit, (size/entryPrice)×(1+feeOpenPct) - includes the opening fee, since it survives the exit-price-to-infinity limit while the closing fee vanishes - null for every other side/contractType combination, which either has no such bound or a trivial one).

Aggregates risk across multiple open positions in one call: total notional, total P&L, total margin in use, margin usage as a % of account balance (if given), and which single position sits closest to liquidation. Each position is computed through the same canonical PnL/liquidation math as the single-position tools, then rolled up. Linear (USDT-margined) positions sum into one USD total; inverse (coin-margined) positions are grouped by settlement coin instead, since a BTC-margined P&L cannot be summed with an ETH-margined one without a live conversion rate. Returns a verdict label, healthy / watch / reduce / critical, which places the closest liquidation distance and margin usage in fixed bands and is not a recommendation. Edge cases: 1 to 50 positions; each needs entry_price, mark_price, size and leverage above zero, mmr 0 to 0.2 and fees 0 to 0.05 as fractions; an inverse position must name its settlement coin; account_balance above zero is optional and without it margin usage is not computed. Positions are not netted against each other. Not covered: correlation between positions, collateral shared across positions, exchange tiered margin, funding, and price moves after the mark price you give. Use when user asks "how exposed am I across all my positions?" or "which of my positions is closest to liquidation?". Position size follows the product-wide convention: base-asset quantity for linear, USD notional (contracts) for inverse. liquidation_price and liq_distance_pct of a position are null when it cannot be liquidated (an inverse short at 1x or less); the closest liquidation skips it.

Core risk/return tearsheet from a single return series: annualized return (compounded, not linear) and volatility, Sharpe (plain + Lo 2002-corrected + Pezier-White skew/kurtosis-adjusted), Sortino, max drawdown, Calmar ratio, the drawdown-ratio cluster (Ulcer Index/Martin ratio, Pain Index/Pain ratio, Burke ratio + modified), Omega-Sharpe ratio, Upside Potential Ratio, skewness, kurtosis, Probabilistic Sharpe Ratio, win rate, best/worst single-period return. Edge cases: at least 3 returns; periods_per_year 1 to 100,000,000 (default 365); mar (minimum acceptable return per period) and benchmark_sharpe default 0; a series with no drawdown makes Calmar an error, a series with no period below mar makes Sortino an error, and a flat series is an error. Not covered: a benchmark return series (alpha, beta, tracking error), fees, taxes, leverage and intraperiod drawdown. Use when user asks for a full risk summary/report on a strategy or portfolio's returns, not just one metric. Returns all of the above in one call. Returns are decimals (0.02 is 2%), at least 3 periods; the call returns an error when the series never draws down (Calmar undefined) or no period falls below mar (Sortino undefined).

Calculate the correct position size given a maximum risk in USDT and a stop-loss price. Edge cases: entryPrice, stopLoss and riskUsdt above zero; leverage above zero (default 1); fees 0 to 0.05; a fee and price combination that makes the risk denominator zero or negative is an error. Not covered: slippage past the stop, funding, exchange lot size and step rounding, and whether the margin is available. Use when user asks "how many coins should I buy?" or "size my position so I risk exactly $X". Returns: positionSize (base), positionUsdt, marginRequired.

Full pre-trade decision card: orchestrates position sizing, breakeven, liquidation, and funding cost in one call. Edge cases: entry_price, leverage above zero; account_balance 0 or more; give desired_size, or stop_loss together with risk_pct, otherwise an error; funding_rate is a decimal per interval (0.0001 is 0.01%) and is read live from the exchange when omitted and exchange (and symbol) are given; hold_hours above zero (default 8); fees 0 to 0.05; mmr 0 to 0.2. Not covered: slippage, tiered margin (use workflow.run_liquidation_live), a funding rate that changes during the hold, and anything about where price will go; the verdict covers setup safety only. Use when user describes a full trade setup and asks "should I take this trade?" or "run the numbers on this setup". Provide exchange+symbol to fetch live funding rate automatically. For an R:R-graded verdict on an entry, stop and target, see workflow.run_risk_reward. Returns: positionSize, breakeven, liquidationPrice, fundingCost, overnightBreakevenShift, verdict. liquidation_price and the liquidation distance are null when the position cannot be liquidated (an inverse short at 1x or less): check for null before using them.

Compares your own probability estimate for an event against a prediction market's price (manual entry, or a live Kalshi ticker, Limitless slug, or Myriad slug) and sizes a bet using fractional Kelly criterion bet sizing (default: quarter-Kelly, a standard conservative haircut on full Kelly, stated explicitly as a convention). Returns a zero Kelly stake whenever your probability doesn't exceed the market's price: no edge. Edge cases: yourProbabilityPct 0.01 to 99.99; give exactly one of marketProbabilityPct (0.01 to 99.99) or a kalshiTicker, limitlessSlug or myriadSlug; bankrollUsd above zero; kellyFractionCap 0.01 to 1 (default quarter-Kelly); no edge (your probability not above the price) gives a zero stake. Not covered: how good your probability is (Kelly with a wrong estimate overbets), fees, slippage, correlated bets, and a limit on market depth. Use when user asks "does this bet have edge?" or "what does Kelly sizing give for my probability estimate against the market's price?". Provide exactly one of marketProbabilityPct/kalshiTicker/limitlessSlug/myriadSlug. Returns: edgePct, evPerDollarStaked, fullKellyFraction, cappedKellyFraction, recommendedStakeUsd, verdict (a label for the size of cappedKellyFraction: skip_this_one/think_twice/worth_the_risk/take_it, not a recommendation). If available is false, do not use any result field (computed figures and any verdict are null or empty), so read available first.

Present value of a future lump sum, a level payment stream, or both: what money received later is worth today at a discount rate. annualRate is a fraction (0.05 = 5%) 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. Payments are level and arrive at the end of each period, or at the start with paymentTiming "begin" (annuity due). Money received is positive, money paid is negative. A bond priced at its coupon rate comes back at its face value. For a list of uneven cash flows use workflow.run_npv. Edge cases: annualRate from -1 to 100 as a fraction (0.05 is 5%) with the rate per period above -100%; years 0 to 1000; periodsPerYear a whole number 1 to 365 (default 1); paymentTiming end (default) or begin; when a payment is given, years times periodsPerYear must be a whole number. A result too large to represent is an error. Not covered: a rate that changes over time, uneven payments (use workflow.run_npv), growing payments, inflation, taxes and fees, and a discount rate that fits the risk (you choose it). Use when user asks "what is $10,000 in 5 years worth today at 6%?" or "what is a 20-year stream of $500 monthly payments worth today?". Returns: presentValue, pvOfFutureValue, pvOfPayments, discountFactor, ratePerPeriod, periods, totalPayments, effectiveAnnualRate.

Cross-exchange agreement check for one perpetual futures price: fetches the same asset USDT/USDC-margined perpetual from a reference set of 7 liquid exchanges (Binance, Bybit, OKX, Gate, KuCoin, Hyperliquid, MEXC; the chosen one is compared against the rest) and reports the median of the others, the spread across all, and how far the chosen exchange sits from that median. Says the exchanges disagree instead of guessing: status is agree (under 0.25%), warn (0.25% to 1%), diverge (1% or more) or insufficient (fewer than 3 other exchanges returned a comparable contract; inverse, dated and unlisted contracts are not compared, and that is not a verdict on the price). Use before acting on a live price: "is this Bybit BTC price in line with the market?" Symbol is the perp symbol as that exchange names it (e.g. BTCUSDT on bybit, ETH-USDT-SWAP on okx). Returns: status, summary, median, peerMedian, spreadPct, deviationPct, sources, quotes (price per exchange), thresholds_pct, as_of. Edge cases: exchange must be a known code and symbol is that exchange own perp name (1 to 60 characters); fewer than 3 comparable peers, an unknown symbol, an inverse or dated contract or a failed quote gives status insufficient with a reason, never a guess. Not covered: order book depth, funding and basis differences between venues, spot prices, and any claim about which exchange is right; it checks agreement of last quotes only.

Risk-parity (equal or custom risk contribution) portfolio weights for N assets: given a covariance matrix (or N return series to compute one from), finds long-only weights where each asset contributes its target share of total portfolio risk. Edge cases: give either returns (at least 2 assets, each series at least 2 values and all the same length) or a square covariance matrix (2 by 2 or larger), never neither; risk_budgets must be positive, finite, one per asset (they are normalized, so they need not sum to 1); an asset with zero or negative variance is an error; non-finite values are an error. Long-only weights. Not covered: shorting, leverage, weight bounds, transaction costs, and estimation error of the covariance (garbage in, garbage out). Use when user asks "what weights give each asset equal risk contribution?" or "how do I risk-parity-weight this portfolio?". A portfolio-construction calculation, not a buy/sell recommendation. Returns: weights, risk_contributions (should match risk_budgets exactly at convergence), portfolio_volatility.

Full risk:reward analysis: takes a trade with entry, stop, AND target (all three). Calculates R:R ratio, position size, liquidation price, breakeven, and P&L at both stop and target. Returns a verdict label, strong (3:1+) / good (2:1+) / marginal / poor, which grades the R:R ratio against fixed thresholds and is not a recommendation. For a full setup check tied to a live exchange/symbol (including funding cost), see workflow.run_pre_trade_check; its verdict covers overall setup safety, not just R:R. Edge cases: entry_price, stop_loss, take_profit, account_balance and leverage above zero; risk_pct above 0 and at most 100; fee_open_pct and fee_close_pct are fractions from 0 to 0.05 (defaults 0.0002 and 0.0005); mmr 0 to 0.2 as a fraction (0.005 is 0.5%); liqFeeRate 0 to 0.05. Stop and target distances are taken as absolute values from the entry, so a stop or target on the wrong side for the chosen side is not rejected: check the side yourself. Not covered: funding payments, slippage, partial fills, exchange tiered margin (use workflow.run_liquidation_live) and any guarantee that a stop fills at its price. Use when user asks "what's my risk reward on this setup?" or "what R:R do this entry, stop and target give?". liquidation_price and the liquidation distance are null when the position cannot be liquidated (an inverse short at 1x or less): check for null before using them.

Scale-out planner: P&L, ROI, and cumulative P&L for each partial exit level. Edge cases: entry_price and total_size above zero; 2 to 10 exits, each price above zero and pct above 0 and at most 100, the pct values summing to at most 100 (less than 100 leaves the rest open); fees are fractions from 0 to 0.05. Not covered: the remainder not sold, funding, slippage, and the chance that each level is reached. Use when user wants to take profit at multiple targets: "close 30% at $90k, 30% at $95k, 40% at $100k, what's my total P&L?". Returns: per-level pnl, weightedAvgExitPrice, totalRoi.

Run a scenario analysis: compute PnL for multiple price-change percentages at once. Edge cases: entryPrice and size above zero; at least one price change in percent; a change of -100 or less is refused for inverse contracts and exactly -100 is allowed for linear only; fees optional (default 0). Not covered: funding, liquidation along the path, slippage, and the probability of each scenario. Use when user asks "show me my P&L if BTC moves -10%, -5%, +5%, +10%". Returns: array of { deltaPct, exitPrice, netPnl, roe }.

Market Profile day-type classifier: trend / balance / neutral_trend / normal / normal_var, from TPO, initial balance, range extension and value migration. Use for "is this a trend day or a balance day?". Returns: structure (the day-type label), description, bias, key_signals, key_levels (VAH/VAL/VPOC/IB/session high-low), tails (session-high/low rejection tails and single prints), scenario_framing, invalidation level. Candles come from the venue when candles[] is omitted (past sessions are cached, so repeats are fast); supplying candles[] makes the run network-free and reproducible. session_date must be a completed UTC session, before today; a session with no candles returns an error. Edge cases: instrument non-empty and venue binance or bybit; session_date is a completed UTC session before today; timeframe 1m, 5m, 15m or 30m (default 15m); value_area_rule 0.5 to 0.9 (default 0.70); supplied candles must each have high at or above low, open and close, low at or below them, and volume 0 or more; a session with no candles is an error. Not covered: order flow beyond the candles given, other venues, and any statement about what price will do; the output describes the session and is not a signal.

Sharpe ratio with the Lo (2002) serial-correlation-aware annualization correction, computed in its lag-1 form rather than the full multi-lag sum (the naive sqrt(periods_per_year) scaling overstates or understates the true annualized Sharpe when returns are autocorrelated), plus the Probabilistic Sharpe Ratio (Bailey & Lopez de Prado): the probability the true Sharpe exceeds a benchmark, adjusted for the sample's skewness/kurtosis and length, not just its point estimate. Edge cases: at least 3 returns; periods_per_year from 1 to 100,000,000 (default 365, the crypto convention); benchmark_sharpe is per period, not annualized (default 0); a flat series (zero standard deviation) is an error. Not covered: the multi-lag Lo correction beyond lag 1, a risk-free rate series (the benchmark is one number), transaction costs, and any statement about future Sharpe. The result describes the sample you give. Use when user asks "what's my real annualized Sharpe, not the naive one?" or "how confident can I be this Sharpe ratio is actually good?". Returns: sharpe_period, sharpe_annualized_naive, sharpe_annualized_lo, autocorrelation_lag1, psr, skewness, kurtosis.

Dollar-cost averaging on a spot coin: the same cash amount bought at each of a list of prices (no leverage, no funding). Returns the coins held, total invested, the average price paid (below the plain average of the prices, because equal cash buys more coins when the price is low), the average cost per coin with the buy fee in it, the break-even sell price and, when currentPrice is given, the value, profit and ROI of selling everything there after the sell fee. amountPerBuy is the cash that leaves the account for one buy, buy fee included. Each fee is a fraction of that fill's trade value (0.001 = 0.1%, at most 0.05). Prices may be in any currency; results are in the same one. The average price is the harmonic mean of the prices; break-even = averageCostPerCoin / (1 - sellFee). Edge cases: 1 to 1000 prices; every price and amountPerBuy must be above zero; a list of one buy is valid; a non-finite result (huge or tiny inputs) is an error; without currentPrice no profit, ROI or proceeds are returned. Not covered: taxes, FIFO/LIFO lots, slippage, withdrawal or network fees, currency conversion, leverage and funding. For buys of unequal size or with sells in between use workflow.run_average_buy_price; for DCA on a perpetual futures position use workflow.run_dca_entry. Use when user asks "I buy $100 of BTC every week at these prices, what is my average and where am I now?". Returns: buys, totalInvested, totalQuantity, averageBuyPrice, averageCostPerCoin, simpleAveragePrice, lowestPrice, highestPrice, totalBuyFees, breakevenSellPrice, and (with currentPrice) currentValue, sellFee, proceeds, profit, roiPct (a fraction).

Payoff, breakeven(s), and max profit/loss for a Deribit BTC/ETH vertical spread (2 legs, same option type, opposite direction, e.g. a bull call spread) or an iron condor/butterfly (4 legs: 2 calls + 2 puts) at a scenario price. Coin-settled, and the max profit/loss are genuinely NOT the flat, textbook USD-settled values: because each leg's own payoff is divided by the settlement price, (1) a debit vertical spread's peak payoff occurs exactly at its short strike, not "anywhere beyond it" - and its profit is a finite WINDOW that closes again at a high enough price, decaying back toward a full loss of the premium paid, and (2) an iron condor/butterfly's max loss is genuinely UNBOUNDED toward price->0 (maxLossCoin: null) if it has a put wing, unlike the "capped at wing width" USD-settled result - only the call side is actually bounded. Edge cases: 2 to 4 legs; strikes and premiums above zero; quantity and scenarioPrice above zero; the leg combination must form a vertical spread, iron condor or iron butterfly, otherwise it is an error naming the problem. Not covered: early exercise, margin, fees, Greeks, legs on different expiries (calendar and diagonal spreads), the probability of profit and the value before expiry. Use when user asks about a bull/bear call/put spread, vertical spread, iron condor, or iron butterfly, e.g. "what's my max loss on this BTC call spread?" or "where do my iron condor breakevens sit?". Returns: structureType (vertical_spread/iron_condor/iron_butterfly, inferred from the legs given), netDebitCoin (negative = credit received), scenarioPayoffCoin, scenarioPnlCoin/Usd, breakevenPrices (0-3, ascending), maxLossCoin/maxProfitCoin (null = unbounded), isProfitable. With exchange "binance" (USDT-settled, flat payoff) the textbook shapes apply instead of the coin-settled ones above: an iron condor's max loss is bounded (wing width less the credit) and a debit spread keeps its full profit above the short strike; it returns: structureType, netDebitUsdt, scenarioPayoffUsdt, scenarioPnlUsdt, breakevenPrices (ascending), maxLossUsdt (the worst P&L, negative when a loss; null = unbounded) and maxProfitUsdt (null = unbounded), isProfitable; USDT is not converted to USD.

Reads the same real-world bet's live price from 2-5 prediction-market venues at once (Kalshi, Polymarket, ADI Predictstreet, Limitless, Myriad) in a single call and reports the spread between the cheapest and most expensive. Takes every venue's identifier together in quotes[], for example one Kalshi ticker and one Polymarket slug for the same bet, and returns the venue with the lowest yes midpoint price, before fees and depth. The caller supplies each venue's own identifier for what they've confirmed is the same underlying bet; this tool never auto-matches events across venues, only reads and compares prices for identifiers you provide. For the odds, breakeven win rate or vig of a single market, see workflow.run_odds_converter. Edge cases: 2 to 5 quotes; each venue is kalshi, polymarket, adi, limitless or myriad with a non-empty identifier; a venue that cannot be read comes back with available false and an error, and spreadPct is null when fewer than 2 quotes resolved. Prices are midpoints, before fees and depth. Not covered: confirming that the identifiers are the same bet (you confirm that), fees, order book depth, and whether the spread can be traded. Use when user asks "is this bet priced differently on Kalshi vs Polymarket?" or "which venue quotes the lowest yes price on this?". Returns: quotes[] (venue, identifier, label, probabilityPct, available, error), availableCount, cheapestVenue, mostExpensiveVenue, spreadPct (percentage points, null if fewer than 2 quotes resolved).

Payoff, P&L, and both breakeven prices for a long or short straddle/strangle (a call + a put on the same Deribit BTC/ETH underlying, both legs the same direction) at a scenario price. A straddle is callStrike === putStrike; any callStrike > putStrike makes it a strangle, same formula either way. Coin-settled like workflow.run_options_payoff: a long position's max loss is the flat total premium paid (between the strikes, both legs worthless); max profit is technically unbounded, dominated by the put leg's payoff as price falls toward zero. Edge cases: callStrike must be at or above putStrike; strikes, premiums and quantity above zero; for the Deribit coin-settled form callPremiumCoin plus putPremiumCoin must be below 1. Not covered: early exercise, margin, fees, Greeks and probability of profit; the result is the payoff at expiry at the one scenario price. Use when user asks about a straddle or strangle, e.g. "what does a BTC straddle pay off if price barely moves?" or "where are my breakevens on this strangle?". Returns: combinedIntrinsicCoin, scenarioPnlCoin, scenarioPnlUsd, upperBreakevenPrice, lowerBreakevenPrice, maxLossCoin/maxProfitCoin (null = unbounded), isStraddle, isProfitable. With exchange "binance" (USDT-settled, flat payoff, callPremiumUsdt and putPremiumUsdt) it returns: totalPremiumUsdt, combinedIntrinsicUsdt, scenarioPnlUsdt, upperBreakevenPrice (call strike + total premium), lowerBreakevenPrice (put strike - total premium, null when that is not above zero), maxLossUsdt/maxProfitUsdt (null = unbounded: the long side's profit is unlimited, the short side's loss is unlimited); USDT is not converted to USD.

Ranks option strategies for a price forecast and a volatility view. You give the spot price, the price you expect at expiry, days to expiry and the market implied volatility; optionally your own volatility forecast (default: the market's, so the view is on price only). Every strategy is built from strikes on a grid around spot, each leg priced with Black-Scholes at the one implied volatility (no skew, no dividends), and the best-fitting version of each family is kept: long call, long put, short put (cash-secured), covered call, protective put, long straddle, long strangle, bull call spread, bear call spread, bull put spread, bear put spread, long call butterfly, short iron condor, short iron butterfly; with allowUnlimitedLoss also naked short call, short straddle and short strangle. The view is a lognormal distribution whose mean is targetPrice and whose volatility is forecastVolPct. Per 1 unit of the underlying (multiply by contract size), each strategy returns its legs, net premium, max profit and max loss (null = unlimited), breakevens, expected profit under the view, probability of profit, and return on risk (expected profit / max loss). rankBy: expectedPnl (default), returnOnRisk (favours far out-of-the-money options) or probabilityOfProfit. Not a recommendation: the result is only as good as the forecast, and premiums are not discounted. Prices are computed, nothing is fetched; for equity options with quoted premiums use workflow.run_options_position. Edge cases: spot and targetPrice 1e-9 to 1e9; daysToExpiry above zero and at most 3650; impliedVolPct and forecastVolPct above zero and at most 1000; riskFreeRatePct 0 to 100; strikeStep above zero, and a step that gives fewer than 3 or too many strikes is an error with the step to use. Not covered: skew, dividends, early exercise, bid-ask spread, commissions, margin, taxes, and strategies with different expiries.

Live price-impact quote for a Solana token swap: routed through Jupiter (the same aggregator real swaps use) across every pool it knows about, not a single-pool estimate. Works in both directions: side "sell" (default) sells a token into USDC or SOL, side "buy" spends USDC or SOL to buy the token. Edge cases: mint a valid Solana base58 address (32 to 48 characters); amount above zero; side sell (default) or buy; outputAsset USDC (default) or SOL. Quotes come live from Jupiter and are a moment in time; an unknown token or no route returns routable false with an error and no figures. Solana only. Not covered: EVM swaps, MEV and sandwiching, priority fees, a price that moves between the quote and your swap, and tokens Jupiter cannot route. Use when user asks "how much slippage will I eat swapping X tokens?", "what will I actually get if I sell N tokens?" or "what do I get buying this token with 500 SOL?". Returns: side, outputAmount (quote asset when selling, tokens when buying), priceImpactPct, effectivePrice (quote asset per token in both directions), marketPriceUsd, liquidityUsd, routable (false + error if the size can't be routed at all).

The sell price that makes a target ROI or a target profit on a spot trade after both fees: the inverse of workflow.run_crypto_profit. Give exactly one of targetRoiPct (a fraction, 0.25 = 25%, negative for a stop price, above -1) or targetProfit (money; needs investment or quantity). Fees are a fraction of each fill's value (0.001 = 0.1%): the buy fee on top of the coins' cost, the sell fee out of the sale value (each fee at most 0.05); prices may be in any currency and results are in the same one; investment is the total cash spent, buy fee included. sellPrice = buyPrice x (1 + buyFee) x (1 + ROI) / (1 - sellFee); a target ROI of 0 is the break-even price. Edge cases: giving both or neither of targetRoiPct and targetProfit is an error; giving both investment and quantity is an error; targetProfit without a size is an error; a target that loses the whole stake or more (ROI of -1 or lower, or cost plus target profit at or below zero) is an error; a negative target gives a stop price below break-even. Not covered: taxes, FIFO/LIFO lots, slippage, withdrawal or network fees, currency conversion, leverage and funding. A target ROI does not depend on the size; with investment or quantity the cost, proceeds, profit and fees are returned too. Use when user asks "at what price do I sell to make 20% after fees?" or "to net $500 on this position, where do I put my limit sell?". Returns: sellPrice, requiredRoiPct (a fraction), priceChangePct, priceMultiple, breakevenSellPrice, and with a size: quantity, totalCost, sellValue, sellFee, proceeds, profit, totalFees (null without one).

Token rug-pull MECHANISM check for a Solana token (mint address): can the deployer still mint supply, freeze wallets, pull liquidity, swap metadata, or has RugCheck flagged a known scam pattern (e.g. copycat token)? Fetches live facts from RugCheck (GoPlus as fallback) and returns a transparently-weighted composite score. Deliberately does NOT score holder concentration or "whale dump" impact: those are properties of any liquid market (a legit protocol's top holders are routinely treasury/vesting/exchange wallets), not rug signals; they are returned separately as informational market_context. Edge cases: mint must be a Solana address; RugCheck is the main source and GoPlus the fallback, and when both fail the call returns an error rather than a score; a brand-new token may have no data yet. The score is a weighted read of public facts at one moment. Not covered: EVM tokens, holder concentration and whale dump risk (returned only as market_context), off-chain team behavior, future changes of authority, and any guarantee of safety. Use when user asks "is this token a rug pull?" or "is [token] safe to buy?". This is a sourced, timestamped read of public facts, not a safety guarantee. Returns: score (0-100), verdict (clean/caution/high_risk/red_flags), verdict_summary, components breakdown, facts, market_context, sources.

Return "unsmoothing" for infrequently-marked/illiquid or appraisal-based series: Getmansky-Lo-Makarov (2004) MA(2) smoothing index plus Blundell-Ward (1987) AR(1) volatility inflation, two complementary models answering "this return series looks smoother than it really is; what's the true volatility?". Edge cases: at least 20 returns; a flat series is an error; if the MA(2) fit does not converge from any starting point, or the lag-1 autocorrelation is 1 or more (Blundell-Ward inflation undefined), the call is an error. Not covered: more than 2 lags of smoothing, tax and fee effects, and proof that the smoothing comes from stale pricing rather than from the strategy. Use when user asks "how much is appraisal smoothing understating my real volatility?" or "what's my de-smoothed Sharpe ratio?". Returns: glm_theta (MA(2) weights), glm_smoothing_index (xi, 1=no smoothing, down to 1/3 for max MA(2) smoothing), glm_true_volatility_multiplier, glm_converged (false if the fit may be unreliable - treat that result with caution), bw_alpha (AR(1) coefficient = lag-1 autocorrelation, can be negative), bw_smoothing_detected (false when alpha<=0: no evidence of smoothing, bw_volatility_multiplier is then pinned to 1 with no correction applied rather than a misleading below-1 value), bw_volatility_multiplier, and each model's own true_stdev estimate.

Market Profile value-area migration across sessions: is value migrating up, down, or overlapping (directional conviction vs balance)? Use for "is value moving higher day over day?". Returns: state, direction, migration_pct, key_levels (current vs. prior session VAH/VAL/VPOC), tails (session-high/low rejection tails and single prints), scenario_framing, invalidation level. Candles come from the venue when candles[] is omitted (past sessions are cached, so repeats are fast); supplying candles[] makes the run network-free and reproducible. session_date must be a completed UTC session, before today; a session with no candles returns an error. Edge cases: instrument non-empty and venue binance or bybit; session_date is a completed UTC session before today; timeframe 1m, 5m, 15m or 30m (default 15m); value_area_rule 0.5 to 0.9 (default 0.70); supplied candles must each have high at or above low, open and close, low at or below them, and volume 0 or more; a session with no candles is an error. lookback_sessions a whole number 1 to 5 (default 1). Not covered: order flow beyond the candles given, other venues, and any statement about what price will do; the output describes the session and is not a signal.

Parametric Value at Risk (VaR) and Conditional VaR / Expected Shortfall (CVaR), the variance-covariance method (assumes normally distributed returns), plus Modified VaR (Cornish-Fisher skew/kurtosis correction, Boudt/Peterson/Croux) when a return series is supplied. Supply either a return series or a mean/stdev pair directly, at a confidence level. Output is at the same periodicity as the input (no automatic annualization) - a daily return series gives a daily VaR/CVaR. Edge cases: give returns (at least 2 values) or both mean and stdev (stdev zero or more), never neither; confidence strictly between 0 and 1 (default 0.95); Modified VaR needs at least 3 returns; a flat series (zero standard deviation) is an error. Not covered: historical or Monte Carlo VaR, fat tails beyond the Cornish-Fisher correction, portfolio aggregation, scaling to another horizon (the result stays in the period of the input). Use when user asks "what's my VaR at 95%/99%?", "what's my expected shortfall on this position?", or "does my Sharpe/VaR estimate need a fat-tails correction?". Returns: var, cvar (both positive loss magnitudes; cvar >= var always), z, mean, stdev, skewness, excess_kurtosis (both null unless 3+ returns were supplied), var_modified (skew/kurtosis-adjusted VaR; null when skewness is, OR when this series' skew/kurtosis are too extreme for the Cornish-Fisher expansion to be a valid quantile - skewness/excess_kurtosis are still returned in that case).

Checks a wallet address (Solana or any of 5 EVM chains) against independent flag databases: GoPlus (malicious-address categories, all chains), Webacy (address analysis + sanctions check, all chains), and ScamSniffer (public phishing/drainer blacklist, EVM chains only), and returns each source's own facts separately, never merged into one invented score. Edge cases: chain solana (default), ethereum, base, bsc, arbitrum or polygon; the address must fit the chain; ScamSniffer covers EVM chains only and is marked not applicable on Solana; a source that fails or has no key is reported as unavailable on its own and does not hide the others. No flag is not a clean bill of health. Not covered: wallets nobody has reported yet, transaction history, counterparty risk, and any legal or sanctions advice. Use when user asks "is this wallet address flagged?" or "is it safe to send to this address?". A clean result means "nothing found in these databases," not a certified-safe verdict. Returns: goplus (flags[], categoriesChecked), webacyGeneral (overallRisk, dprk/hack/ofacSanctioned, exchangeLabel), webacySanctions (status), scamSniffer (flagged; not applicable on Solana). Each source has an `available` flag: false + error if that source failed independently.

Theoretical fair value for a time-windowed crypto up/down contract (the shape ADI Predictstreet and Kalshi-style daily crypto markets use: pays out based on whether the settlement price finishes at/above or below a reference price pinned at window open, by a fixed close time): a cash-or-nothing digital option, priced with the standard N(d2) formula. It gives the probability at the close time only, not the probability of touching a level at any point before it (first passage). Time convention: a year is 365 days. Use this when there's no live market price to read (e.g. a venue's contract has real terms but zero trading volume) instead of a live-market odds tool. Volatility is a required manual input; there is no live implied-vol market on these contracts to pull it from. Edge cases: currentPrice, referencePrice, minutesToClose and volatilityPct (annualized) above zero; riskFreeRatePct 0 to 100 (default 0); the volatility is yours, nothing is estimated; a year is 365 days. The result is the probability at the close only, not of touching the level before it. Not covered: first-passage (touch) probability, volatility that changes, jumps, the venue fees, order book prices, and the exact settlement rule of the venue. Use when user asks "what does the N(d2) model give for this up/down contract?" or "what's the model probability BTC finishes above $X in N minutes?". Returns: d1, d2, probAbovePct, probBelowPct, fairPriceAboveCents, fairPriceBelowCents (cents convention, directly comparable to how these venues quote a contract).

Run up to 10 calls of other tools in one request and get all results back together, in order. Each entry is {name, arguments} exactly as for a single call; each result carries its own signature block, so every one verifies on its own. The batch call itself is free: every entry counts as one call against the daily limit. A failed entry does not stop the others (it comes back with an error), except that once the daily limit is reached or the batch has run for about 20 seconds, the entries after that point are not run and not counted: the reply says so for each, so send them again. A batch cannot contain a batch. Entries run one after another, in order, and none sees the output of another.

Return the ECDSA P-256 public key (PEM + JWK) and canonical signing format used to sign tool responses, so results can be verified offline without calling back to TradingCalc. Every tools/call result includes a signed second content block when signing is configured; also available at GET /api/mcp/pubkey.

Run the full regression suite: 60 canonical test vectors (linear and inverse/coin-margined) across all 12 calculators, and return a pass/fail report with counts and timestamp. Useful as a health check before relying on results in production workflows.

Calculate the weighted average entry price from multiple buy/sell fills (DCA): the bare number only, no breakeven or per-fill breakdown. Edge cases: symbol non-empty; at least one fill, each price and quantity above zero (size is accepted as quantity); leverage above zero is optional. The average is weighted by quantity. Not covered: fees, sells or partial closes (give only the fills still open), and funding. Use when user asks only "what's my average entry?" and wants just that figure. Each fill is { price, quantity } here (workflow.run_dca_entry calls the same field size). For breakeven and a per-level summary too, use workflow.run_dca_entry instead. Returns: averagePrice, totalSize, totalCost.

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. Edge cases: spotSize above zero (USD value); hedgeRatio 0 to 200 percent (default 100); leverage 1 or more (default 1); fundingRatePct in percent per interval (0.01 is 0.01%, default 0.01); intervalHours 0.25 to 24 (default 8); an inverse contract needs entryPrice. Not covered: basis risk between spot and the perp, rebalancing as prices move, margin calls, and a funding rate that changes. 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.