Deterministic options, forex, risk, on-chain & futures math. 75 tools. Not AI estimates.
TradingCalc MCP Server (io.github.SKalinin909/tradingcalc)
This MCP server provides deterministic crypto futures math for trade planning and analysis. It calculates PnL, liquidation outcomes, position sizing, and carry trade metrics. The dataset indicates 19 tools are available, and the service is intended to return exact numbers rather than AI estimates.
🛠️ Key Features
Crypto futures math
PnL calculations
Liquidation and margin-related computations
Position sizing
Carry trade / funding-related calculations
Market-structure analysis via Market Profile
Tool availability: 23 tools
🚀 Use Cases
Compute PnL for leveraged long/short trades
Determine liquidation implications for given leverage and pricing
Size a position from account size and risk/stop levels
Evaluate whether a carry trade is worth it using funding rates and duration
Calculate net PnL, ROE, fees and gross profit/loss for a futures trade. 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).
Parameters7
side
string
required
Trade direction
entryPrice
number
required
Entry price (positive)
exitPrice
number
required
Exit price (positive)
size
number
required
Position size: base asset qty for linear, USD contracts for inverse
feeOpenPct
number
optional
Opening fee as fraction, e.g. 0.0002 = 0.02%
feeClosePct
number
optional
Closing fee as fraction
contractType
string
optional
linear = USDT-margined (default), inverse = coin-margined. For inverse, pnl/fees are returned in the base coin, not USDT.
Raw schema
{
"type": "object",
"properties": {
"side": {
"type": "string",
"enum": [
"long",
"short"
],
"description": "Trade direction"
},
"entryPrice": {
"type": "number",
"description": "Entry price (positive)"
},
"exitPrice": {
"type": "number",
"description": "Exit price (positive)"
},
"size": {
"type": "number",
"description": "Position size: base asset qty for linear, USD contracts for inverse"
},
"feeOpenPct": {
"type": "number",
"description": "Opening fee as fraction, e.g. 0.0002 = 0.02%"
},
"feeClosePct": {
"type": "number",
"description": "Closing fee as fraction"
},
"contractType": {
"type": "string",
"enum": [
"linear",
"inverse"
],
"description": "linear = USDT-margined (default), inverse = coin-margined. For inverse, pnl/fees are returned in the base coin, not USDT."
}
},
"required": [
"side",
"entryPrice",
"exitPrice",
"size"
]
}
workflow.run_liquidation_safety
Calculate the liquidation price for an isolated-margin futures position. Use when user asks "where will I get liquidated?" or "how close is my liq price?". Returns: liquidationPrice, distancePct (how far from entry).
Calculate the break-even exit price that covers all trading fees: this alone, nothing else. 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.
Parameters6
side
string
required
entryPrice
number
required
Entry price (positive)
sizeBase
number
required
Position size: base asset qty for linear, USD contracts for inverse
feeOpenPct
number
optional
Opening fee fraction, default 0.0002
feeClosePct
number
optional
Closing fee fraction, default 0.0005
contractType
string
optional
linear = USDT-margined (default), inverse = coin-margined. For inverse, totalFees is returned in the base coin.
Calculate the correct position size given a maximum risk in USDT and a stop-loss price. Use when user asks "how many coins should I buy?" or "size my position so I risk exactly $X". Returns: positionSize (base), positionUsdt, marginRequired.
Parameters8
side
string
required
entryPrice
number
required
Entry price
stopLoss
number
required
Stop-loss price
riskUsdt
number
required
Maximum acceptable loss in USDT
leverage
number
optional
Leverage, default 1
feeOpenPct
number
optional
Opening fee fraction, default 0.0002
feeClosePct
number
optional
Closing fee fraction, default 0.0005
contractType
string
optional
linear = USDT-margined (default), inverse = coin-margined. For inverse, sizeQuote is USD contracts and margin is returned in the base coin.
Calculate the total funding cost (or income) for holding a perpetual futures position. Use when user asks "how much funding will I pay holding X days?" or "is funding eating my profit?". Returns: totalFundingUsdt (negative = you pay, positive = you receive), perIntervalUsdt.
Parameters6
side
string
required
sizeBase
number
required
Position size in base asset
entryPrice
number
required
Entry price
fundingRate
number
required
Funding rate per 8h period as fraction, e.g. 0.0001
days
number
required
Number of days to hold
contractType
string
optional
linear = USDT-margined (default), inverse = coin-margined. For inverse, sizeBase is USD contracts and cost figures come out in the base coin.
Raw schema
{
"type": "object",
"properties": {
"side": {
"type": "string",
"enum": [
"long",
"short"
]
},
"sizeBase": {
"type": "number",
"description": "Position size in base asset"
},
"entryPrice": {
"type": "number",
"description": "Entry price"
},
"fundingRate": {
"type": "number",
"description": "Funding rate per 8h period as fraction, e.g. 0.0001"
},
"days": {
"type": "number",
"description": "Number of days to hold"
},
"contractType": {
"type": "string",
"enum": [
"linear",
"inverse"
],
"description": "linear = USDT-margined (default), inverse = coin-margined. For inverse, sizeBase is USD contracts and cost figures come out in the base coin."
}
},
"required": [
"side",
"sizeBase",
"entryPrice",
"fundingRate",
"days"
]
}
primitive.average_entry
Calculate the weighted average entry price from multiple buy/sell fills (DCA): the bare number only, no breakeven or per-fill breakdown. Use when user asks only "what's my average entry?" and wants just that figure. For breakeven and a per-level summary too, use workflow.run_dca_entry instead. Returns: averagePrice, totalSize, totalCost.
Parameters4
symbol
string
required
Trading pair symbol, e.g. BTCUSDT
exchangeCode
string
optional
Exchange identifier (optional)
input
object
required
contractType
string
optional
linear = USDT-margined, average is the arithmetic mean (default). inverse = coin-margined, average is the harmonic mean (fill quantity is USD notional).
Calculate the exact exit price needed to hit a target PnL or ROE percentage. Use when user asks "at what price do I take profit to make $500?" or "where should I set TP for 20% ROE?". Returns: targetExitPrice.
Parameters9
side
string
required
entryPrice
number
required
Entry price
leverage
number
required
Leverage multiplier
sizeBase
number
required
Position size in base asset
targetMode
string
required
"pnl" = target in USDT, "roe" = target in %
targetValue
number
required
Target value (USDT/coin for pnl mode, or %)
feeOpenPct
number
optional
Opening fee fraction, default 0.0002
feeClosePct
number
optional
Closing fee fraction, default 0.0005
contractType
string
optional
linear = USDT-margined (default), inverse = coin-margined. For inverse, pnl-mode targetValue and outputs are in the base coin.
Run a scenario analysis: compute PnL for multiple price-change percentages at once. Use when user asks "show me my P&L if BTC moves -10%, -5%, +5%, +10%". Returns: array of { deltaPct, exitPrice, netPnl, roe }.
Parameters7
side
string
required
entryPrice
number
required
Entry price
size
number
required
Position size in base asset
deltasPct
array
required
List of price change percentages, e.g. [-10, -5, 0, 5, 10]
feeOpenPct
number
optional
Opening fee fraction
feeClosePct
number
optional
Closing fee fraction
contractType
string
optional
linear = USDT-margined (default), inverse = coin-margined. For inverse, size is USD contracts and pnl/fees come out in the base coin.
Raw schema
{
"type": "object",
"properties": {
"side": {
"type": "string",
"enum": [
"long",
"short"
]
},
"entryPrice": {
"type": "number",
"description": "Entry price"
},
"size": {
"type": "number",
"description": "Position size in base asset"
},
"deltasPct": {
"type": "array",
"items": {
"type": "number"
},
"description": "List of price change percentages, e.g. [-10, -5, 0, 5, 10]"
},
"feeOpenPct": {
"type": "number",
"description": "Opening fee fraction"
},
"feeClosePct": {
"type": "number",
"description": "Closing fee fraction"
},
"contractType": {
"type": "string",
"enum": [
"linear",
"inverse"
],
"description": "linear = USDT-margined (default), inverse = coin-margined. For inverse, size is USD contracts and pnl/fees come out in the base coin."
}
},
"required": [
"side",
"entryPrice",
"size",
"deltasPct"
]
}
workflow.run_max_leverage
Calculate the maximum safe leverage based on account size, max acceptable drawdown, and asset daily volatility. Use when user asks "what's the max leverage I should use on BTC?" or "how much leverage is safe given 3% daily volatility?". Returns: maxLeverage, marginAtRisk.
Parameters4
accountSize
number
required
Total account size in USDT
maxDrawdownPct
number
required
Maximum acceptable drawdown as percentage, e.g. 10 for 10%
volatilityPct
number
required
Expected daily price volatility as percentage, e.g. 3 for 3%
mmr
number
optional
Maintenance margin rate, default 0.005 (0.5%)
Raw schema
{
"type": "object",
"properties": {
"accountSize": {
"type": "number",
"description": "Total account size in USDT"
},
"maxDrawdownPct": {
"type": "number",
"description": "Maximum acceptable drawdown as percentage, e.g. 10 for 10%"
},
"volatilityPct": {
"type": "number",
"description": "Expected daily price volatility as percentage, e.g. 3 for 3%"
},
"mmr": {
"type": "number",
"description": "Maintenance margin rate, default 0.005 (0.5%)"
}
},
"required": [
"accountSize",
"maxDrawdownPct",
"volatilityPct"
]
}
primitive.hedge_ratio
Calculate the short perpetual futures position size needed to hedge a spot holding. Use when user asks "how much should I short to hedge my BTC?" or "what margin do I need for a 100% hedge?". Returns: hedgeNotional, requiredMargin, estimatedFundingCost.
Parameters4
spotSize
number
required
Spot position value in USDT
hedgeRatio
number
optional
Percentage of spot to hedge, e.g. 100 for full hedge, 50 for half. Default 100.
leverage
number
optional
Leverage on the perp short. Default 1.
fundingRatePct
number
optional
Current 8h funding rate as percentage, e.g. 0.01. Used for cost estimate.
Raw schema
{
"type": "object",
"properties": {
"spotSize": {
"type": "number",
"description": "Spot position value in USDT"
},
"hedgeRatio": {
"type": "number",
"description": "Percentage of spot to hedge, e.g. 100 for full hedge, 50 for half. Default 100."
},
"leverage": {
"type": "number",
"description": "Leverage on the perp short. Default 1."
},
"fundingRatePct": {
"type": "number",
"description": "Current 8h funding rate as percentage, e.g. 0.01. Used for cost estimate."
}
},
"required": [
"spotSize"
]
}
workflow.run_funding_arbitrage
Calculate funding rate arbitrage profit: annualized yield, net profit, and breakeven days for a long/short basis trade across two exchanges: the bare numbers only, no plain-English verdict. For the same math plus a profitable/marginal/loss verdict, use workflow.run_carry_trade instead. Use when user asks "is this funding arb worth it?" or "how many days to break even on transfer fees?". Returns: netProfitUsdt, annualizedYieldPct, breakevenDays.
Parameters6
positionSize
number
required
Position size in USDT
longFundingRate
number
required
Funding rate on long side (% per interval, positive = you pay)
shortFundingRate
number
required
Funding rate on short side (% per interval, positive = you receive)
transferFeePct
number
optional
One-time transfer/setup fee as percentage, e.g. 0.1 for 0.1%
durationDays
number
required
Holding period in days
intervalHours
number
optional
Funding interval: 8 (standard) or 1 (Hyperliquid)
Raw schema
{
"type": "object",
"properties": {
"positionSize": {
"type": "number",
"description": "Position size in USDT"
},
"longFundingRate": {
"type": "number",
"description": "Funding rate on long side (% per interval, positive = you pay)"
},
"shortFundingRate": {
"type": "number",
"description": "Funding rate on short side (% per interval, positive = you receive)"
},
"transferFeePct": {
"type": "number",
"description": "One-time transfer/setup fee as percentage, e.g. 0.1 for 0.1%"
},
"durationDays": {
"type": "number",
"description": "Holding period in days"
},
"intervalHours": {
"type": "number",
"enum": [
8,
1
],
"description": "Funding interval: 8 (standard) or 1 (Hyperliquid)"
}
},
"required": [
"positionSize",
"longFundingRate",
"shortFundingRate",
"durationDays"
]
}
workflow.run_compound_funding
Project capital growth from reinvesting perpetual futures funding income (compounding carry). Use when user asks "how much will I make compounding 0.01% funding for 90 days?" or "what's my APY on this carry position?". Returns: finalCapital, totalEarned, apy, growthTable.
Parameters5
initialCapital
number
required
Starting capital in USDT
fundingRatePct
number
required
Funding rate per interval as percentage, e.g. 0.01 for 0.01%
intervalHours
number
optional
Funding interval: 8 (standard) or 1 (Hyperliquid)
durationDays
number
required
Number of days to project
reinvestPct
number
optional
Percentage of earnings reinvested each interval. 100 = full compounding, 0 = no reinvestment. Default 100.
Raw schema
{
"type": "object",
"properties": {
"initialCapital": {
"type": "number",
"description": "Starting capital in USDT"
},
"fundingRatePct": {
"type": "number",
"description": "Funding rate per interval as percentage, e.g. 0.01 for 0.01%"
},
"intervalHours": {
"type": "number",
"enum": [
8,
1
],
"description": "Funding interval: 8 (standard) or 1 (Hyperliquid)"
},
"durationDays": {
"type": "number",
"description": "Number of days to project"
},
"reinvestPct": {
"type": "number",
"description": "Percentage of earnings reinvested each interval. 100 = full compounding, 0 = no reinvestment. Default 100."
}
},
"required": [
"initialCapital",
"fundingRatePct",
"durationDays"
]
}
workflow.run_pre_trade_check
Full pre-trade decision card: orchestrates position sizing, breakeven, liquidation, and funding cost in one call: the preferred tool whenever a full setup check is wanted, not just one metric. 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. If the user specifically gave an entry/stop/target and wants an R:R-graded verdict, use workflow.run_risk_reward instead. Returns: positionSize, breakeven, liquidationPrice, fundingCost, overnightBreakevenShift, verdict.
Parameters14
exchange
string
optional
Exchange code, e.g. "binance" or "bybit". Used to fetch live funding rate if funding_rate is omitted.
symbol
string
optional
Perpetual symbol, e.g. "BTCUSDT".
side
string
required
entry_price
number
required
Entry price (positive)
stop_loss
number
required
Stop-loss price (positive)
account_balance
number
required
Total account balance in USDT
risk_pct
number
required
Risk as % of balance, e.g. 1.0 = 1%
leverage
number
required
Leverage multiplier
funding_rate
number
optional
Funding rate per 8h as decimal, e.g. 0.0001. If omitted, fetched live from exchange.
hold_hours
number
optional
Expected hold time in hours for overnight shift calc. Default 8.
fee_open_pct
number
optional
Opening fee fraction, default 0.0002
fee_close_pct
number
optional
Closing fee fraction, default 0.0005
mmr
number
optional
Maintenance margin rate, default 0.005
contractType
string
optional
linear = USDT-margined (default), inverse = coin-margined (e.g. Bybit BTCUSD). All returned figures (notional, margin, risk_amount, funding_cost_*) stay USD-denominated either way; recommended_size is USD notional (contracts) for inverse.
Raw schema
{
"type": "object",
"properties": {
"exchange": {
"type": "string",
"description": "Exchange code, e.g. \"binance\" or \"bybit\". Used to fetch live funding rate if funding_rate is omitted."
},
"symbol": {
"type": "string",
"description": "Perpetual symbol, e.g. \"BTCUSDT\"."
},
"side": {
"type": "string",
"enum": [
"long",
"short"
]
},
"entry_price": {
"type": "number",
"description": "Entry price (positive)"
},
"stop_loss": {
"type": "number",
"description": "Stop-loss price (positive)"
},
"account_balance": {
"type": "number",
"description": "Total account balance in USDT"
},
"risk_pct": {
"type": "number",
"description": "Risk as % of balance, e.g. 1.0 = 1%"
},
"leverage": {
"type": "number",
"description": "Leverage multiplier"
},
"funding_rate": {
"type": "number",
"description": "Funding rate per 8h as decimal, e.g. 0.0001. If omitted, fetched live from exchange."
},
"hold_hours": {
"type": "number",
"description": "Expected hold time in hours for overnight shift calc. Default 8."
},
"fee_open_pct": {
"type": "number",
"description": "Opening fee fraction, default 0.0002"
},
"fee_close_pct": {
"type": "number",
"description": "Closing fee fraction, default 0.0005"
},
"mmr": {
"type": "number",
"description": "Maintenance margin rate, default 0.005"
},
"contractType": {
"type": "string",
"enum": [
"linear",
"inverse"
],
"description": "linear = USDT-margined (default), inverse = coin-margined (e.g. Bybit BTCUSD). All returned figures (notional, margin, risk_amount, funding_cost_*) stay USD-denominated either way; recommended_size is USD notional (contracts) for inverse."
}
},
"required": [
"side",
"entry_price",
"stop_loss",
"account_balance",
"risk_pct",
"leverage"
]
}
workflow.run_risk_reward
Full risk:reward analysis: the single best tool when user describes 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: strong (3:1+) / good (2:1+) / marginal / poor, specifically graded on the R:R ratio. If the user instead wants a full setup check tied to a live exchange/symbol (including funding cost), use workflow.run_pre_trade_check instead; its verdict covers overall setup safety, not just R:R. Use when user asks "is this trade worth taking?" or "what's my risk reward on this setup?".
Parameters11
side
string
required
entry_price
number
required
Entry price
stop_loss
number
required
Stop-loss price
take_profit
number
required
Take-profit price
account_balance
number
required
Account balance in USDT
risk_pct
number
required
Max risk as % of account
leverage
number
required
Leverage multiplier
fee_open_pct
number
optional
Open fee rate (default 0.0002)
fee_close_pct
number
optional
Close fee rate (default 0.0005)
mmr
number
optional
Maintenance margin rate (default 0.005)
contractType
string
optional
linear = USDT-margined (default), inverse = coin-margined (e.g. Bybit BTCUSD). position_size/notional are USD notional (contracts) for inverse; pnl_at_stop/pnl_at_target come back denominated in the base coin.
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: healthy / watch / reduce / critical, driven by the closest liquidation distance and margin usage. 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.
Parameters2
positions
array
required
account_balance
number
optional
Optional account balance in USD, used to compute margin_usage_pct: linear margin plus every inverse position's own margin marked to market at its mark_price, all as one USD total
Raw schema
{
"type": "object",
"properties": {
"positions": {
"type": "array",
"minItems": 1,
"maxItems": 50,
"items": {
"type": "object",
"properties": {
"label": {
"type": "string",
"description": "Optional label to identify this position in the response (defaults to \"Position N\")"
},
"side": {
"type": "string",
"enum": [
"long",
"short"
]
},
"entry_price": {
"type": "number",
"description": "Entry price"
},
"mark_price": {
"type": "number",
"description": "Current mark/last price"
},
"size": {
"type": "number",
"description": "Position size: base-asset quantity for linear, USD notional (contracts) for inverse"
},
"leverage": {
"type": "number",
"description": "Leverage multiplier"
},
"fee_open_pct": {
"type": "number",
"description": "Open fee rate (default 0.0002)"
},
"fee_close_pct": {
"type": "number",
"description": "Close fee rate (default 0.0005)"
},
"mmr": {
"type": "number",
"description": "Maintenance margin rate (default 0.005)"
},
"contractType": {
"type": "string",
"enum": [
"linear",
"inverse"
],
"description": "linear = USDT-margined (default), inverse = coin-margined (e.g. Bybit BTCUSD)"
},
"coin": {
"type": "string",
"description": "Settlement coin, required when contractType is inverse (e.g. \"BTC\", \"ETH\")"
}
},
"required": [
"side",
"entry_price",
"mark_price",
"size",
"leverage"
]
}
},
"account_balance": {
"type": "number",
"description": "Optional account balance in USD, used to compute margin_usage_pct: linear margin plus every inverse position's own margin marked to market at its mark_price, all as one USD total"
}
},
"required": [
"positions"
]
}
workflow.run_dca_entry
DCA entry planner: weighted average entry price, breakeven, and per-level contribution from multiple fill prices and sizes. Prefer this over primitive.average_entry whenever breakeven or the per-level breakdown is also wanted, not just the bare average. Use when user bought at several prices and asks "what's my average entry?" or "where is my DCA breakeven?". Returns: averageEntry, breakeven, per-level summary.
Parameters5
side
string
required
entries
array
required
fee_open_pct
number
optional
Open fee rate (default 0.0002)
fee_close_pct
number
optional
Close fee rate (default 0.0005)
contractType
string
optional
linear = USDT-margined (default), inverse = coin-margined. Each fill's size is USD notional (contracts) for inverse; averageEntry is then the harmonic mean of fill prices, not the arithmetic mean.
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. Use when user asks "should I add to this losing position?" or "what does averaging down actually cost me here?".
Parameters11
side
string
required
existing_entry_price
number
required
Entry price of the position already held
existing_size
number
required
Size already held: base-asset quantity for linear, USD notional (contracts) for inverse
add_price
number
required
Proposed price to add at - also treated as today's current price for the fresh-entry comparison
add_size
number
required
Additional size being considered, same unit convention as existing_size
stop_loss
number
required
Stop-loss price (must be below add_price for a long, above it for a short - the position should already be closed otherwise)
leverage
number
required
Leverage multiplier
fee_open_pct
number
optional
Open fee rate (default 0.0002)
fee_close_pct
number
optional
Close fee rate (default 0.0005)
mmr
number
optional
Maintenance margin rate (default 0.005)
contractType
string
optional
linear = USDT-margined (default), inverse = coin-margined. Risk figures come back denominated in the base coin for inverse.
Raw schema
{
"type": "object",
"properties": {
"side": {
"type": "string",
"enum": [
"long",
"short"
]
},
"existing_entry_price": {
"type": "number",
"description": "Entry price of the position already held"
},
"existing_size": {
"type": "number",
"description": "Size already held: base-asset quantity for linear, USD notional (contracts) for inverse"
},
"add_price": {
"type": "number",
"description": "Proposed price to add at - also treated as today's current price for the fresh-entry comparison"
},
"add_size": {
"type": "number",
"description": "Additional size being considered, same unit convention as existing_size"
},
"stop_loss": {
"type": "number",
"description": "Stop-loss price (must be below add_price for a long, above it for a short - the position should already be closed otherwise)"
},
"leverage": {
"type": "number",
"description": "Leverage multiplier"
},
"fee_open_pct": {
"type": "number",
"description": "Open fee rate (default 0.0002)"
},
"fee_close_pct": {
"type": "number",
"description": "Close fee rate (default 0.0005)"
},
"mmr": {
"type": "number",
"description": "Maintenance margin rate (default 0.005)"
},
"contractType": {
"type": "string",
"enum": [
"linear",
"inverse"
],
"description": "linear = USDT-margined (default), inverse = coin-margined. Risk figures come back denominated in the base coin for inverse."
}
},
"required": [
"side",
"existing_entry_price",
"existing_size",
"add_price",
"add_size",
"stop_loss",
"leverage"
]
}
workflow.run_scale_out
Scale-out planner: P&L, ROI, and cumulative P&L for each partial exit level. 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.
Parameters7
side
string
required
entry_price
number
required
Entry price
total_size
number
required
Total position size in base currency
exits
array
required
fee_open_pct
number
optional
Open fee rate (default 0.0002)
fee_close_pct
number
optional
Close fee rate (default 0.0005)
contractType
string
optional
linear = USDT-margined (default), inverse = coin-margined. total_size is USD notional (contracts) for inverse, and per-level pnl comes back denominated in the base coin.
Delta-neutral carry trade (funding arbitrage) analysis, with a profitable/marginal/loss verdict on top of the same math primitive.funding_arb uses. Prefer this over primitive.funding_arb whenever a plain-English verdict is wanted, not just the raw numbers. Use when user asks "is this carry trade worth it?": long on exchange A, short on exchange B, collect the funding rate spread. Returns: netYieldPct, grossProfit, netProfit, breakevenDays, verdict (profitable/marginal/loss).
Parameters6
notional
number
required
Position notional in USDT
funding_rate_long
number
required
Funding rate on long exchange per interval (decimal)
funding_rate_short
number
required
Funding rate on short exchange per interval (decimal)
transfer_fee_pct
number
optional
One-way transfer fee % (default 0.1)
hold_days
number
required
Hold duration in days
interval_hours
number
optional
Funding interval: 1 or 8 hours (default 8)
Raw schema
{
"type": "object",
"properties": {
"notional": {
"type": "number",
"description": "Position notional in USDT"
},
"funding_rate_long": {
"type": "number",
"description": "Funding rate on long exchange per interval (decimal)"
},
"funding_rate_short": {
"type": "number",
"description": "Funding rate on short exchange per interval (decimal)"
},
"transfer_fee_pct": {
"type": "number",
"description": "One-way transfer fee % (default 0.1)"
},
"hold_days": {
"type": "number",
"description": "Hold duration in days"
},
"interval_hours": {
"type": "number",
"enum": [
1,
8
],
"description": "Funding interval: 1 or 8 hours (default 8)"
}
},
"required": [
"notional",
"funding_rate_long",
"funding_rate_short",
"hold_days"
]
}
workflow.run_funding_breakeven
Price move needed to cover funding cost + fees over a holding period. Use when user asks "how much does BTC need to move for me to profit after funding?" or "is funding killing my edge on this trade?". Returns: breakevenWithFunding, breakevenWithoutFunding, requiredMovePct.
Parameters8
side
string
required
entry_price
number
required
Entry price
size
number
required
Position size in base currency
funding_rate
number
required
Funding rate per 8h period (decimal, e.g. 0.0001)
hold_hours
number
required
Hold duration in hours
fee_open_pct
number
optional
Open fee rate (default 0.0002)
fee_close_pct
number
optional
Close fee rate (default 0.0005)
contractType
string
optional
linear = USDT-margined (default), inverse = coin-margined. size is USD notional (contracts) for inverse; notional/funding_cost/fee_total/total_carry_cost come back denominated in the base coin.
Raw schema
{
"type": "object",
"properties": {
"side": {
"type": "string",
"enum": [
"long",
"short"
]
},
"entry_price": {
"type": "number",
"description": "Entry price"
},
"size": {
"type": "number",
"description": "Position size in base currency"
},
"funding_rate": {
"type": "number",
"description": "Funding rate per 8h period (decimal, e.g. 0.0001)"
},
"hold_hours": {
"type": "number",
"description": "Hold duration in hours"
},
"fee_open_pct": {
"type": "number",
"description": "Open fee rate (default 0.0002)"
},
"fee_close_pct": {
"type": "number",
"description": "Close fee rate (default 0.0005)"
},
"contractType": {
"type": "string",
"enum": [
"linear",
"inverse"
],
"description": "linear = USDT-margined (default), inverse = coin-margined. size is USD notional (contracts) for inverse; notional/funding_cost/fee_total/total_carry_cost come back denominated in the base coin."
}
},
"required": [
"side",
"entry_price",
"size",
"funding_rate",
"hold_hours"
]
}
workflow.run_bonding_curve
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). 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).
Parameters2
solRaisedSoFar
number
required
SOL already raised on the curve so far (0 for a brand-new token)
solToSpend
number
required
SOL amount for this buy
Raw schema
{
"type": "object",
"properties": {
"solRaisedSoFar": {
"type": "number",
"description": "SOL already raised on the curve so far (0 for a brand-new token)"
},
"solToSpend": {
"type": "number",
"description": "SOL amount for this buy"
}
},
"required": [
"solRaisedSoFar",
"solToSpend"
]
}
workflow.run_impermanent_loss
Impermanent loss for a liquidity-pool position: compares providing liquidity against simply holding the same tokens, at a manually-supplied entry and current price. Two modes: full_range (standard 50/50 constant-product pool, the textbook 2*sqrt(k)/(1+k)-1 closed form) or concentrated (a Uniswap-V3-style position confined to [lowerPrice, upperPrice] - IL is always worse than full_range for the same price move when the range is tight, and the position is fully single-asset, no longer earning fees, once price exits the range). impermanentLossPct is always <= 0 and is measured relative to the quote token (dimensionless, exact regardless of what the quote token is); the optional dollar figures additionally assume the quote token's own USD price stayed roughly stable (true for a stablecoin-quoted pool). Use when user asks "how much am I losing to impermanent loss?" or "is this LP position still worth it after fees?". Returns: impermanentLossPct, lpValueMultiplier, hodlValueMultiplier, inRange, lossUsd/netResultUsd (null unless depositValueUsd given).
Parameters7
mode
string
optional
Default full_range.
entryPrice
number
required
Base token's price in quote-token terms when liquidity was deposited
currentPrice
number
required
Base token's current price in quote-token terms
lowerPrice
number
optional
Range lower bound - required for concentrated mode, must be below entryPrice
upperPrice
number
optional
Range upper bound - required for concentrated mode, must be above entryPrice
depositValueUsd
number
optional
Optional: USD value deposited at entry, to also report dollar-denominated lpValueUsd/hodlValueUsd/lossUsd
feesEarnedUsd
number
optional
Optional trading fees earned so far in USD (default 0), folded into netResultUsd alongside lossUsd
Raw schema
{
"type": "object",
"properties": {
"mode": {
"type": "string",
"enum": [
"full_range",
"concentrated"
],
"description": "Default full_range."
},
"entryPrice": {
"type": "number",
"description": "Base token's price in quote-token terms when liquidity was deposited"
},
"currentPrice": {
"type": "number",
"description": "Base token's current price in quote-token terms"
},
"lowerPrice": {
"type": "number",
"description": "Range lower bound - required for concentrated mode, must be below entryPrice"
},
"upperPrice": {
"type": "number",
"description": "Range upper bound - required for concentrated mode, must be above entryPrice"
},
"depositValueUsd": {
"type": "number",
"description": "Optional: USD value deposited at entry, to also report dollar-denominated lpValueUsd/hodlValueUsd/lossUsd"
},
"feesEarnedUsd": {
"type": "number",
"description": "Optional trading fees earned so far in USD (default 0), folded into netResultUsd alongside lossUsd"
}
},
"required": [
"entryPrice",
"currentPrice"
]
}
workflow.run_options_payoff
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. 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.
Parameters7
currency
string
optional
Underlying coin. Default BTC.
optionType
string
required
position
string
required
strike
number
required
Strike price in USD
premiumCoin
number
required
Premium paid/received per contract, in the base coin (matches Deribit's own quoted price, e.g. 0.02 BTC); must be < 1 for a call
quantity
number
required
Number of contracts (Deribit BTC/ETH options have contract_size 1.0, so this is coin-denominated size)
scenarioPrice
number
required
Underlying price in USD to evaluate the payoff at
Raw schema
{
"type": "object",
"properties": {
"currency": {
"type": "string",
"enum": [
"BTC",
"ETH"
],
"description": "Underlying coin. Default BTC."
},
"optionType": {
"type": "string",
"enum": [
"call",
"put"
]
},
"position": {
"type": "string",
"enum": [
"long",
"short"
]
},
"strike": {
"type": "number",
"description": "Strike price in USD"
},
"premiumCoin": {
"type": "number",
"description": "Premium paid/received per contract, in the base coin (matches Deribit's own quoted price, e.g. 0.02 BTC); must be < 1 for a call"
},
"quantity": {
"type": "number",
"description": "Number of contracts (Deribit BTC/ETH options have contract_size 1.0, so this is coin-denominated size)"
},
"scenarioPrice": {
"type": "number",
"description": "Underlying price in USD to evaluate the payoff at"
}
},
"required": [
"optionType",
"position",
"strike",
"premiumCoin",
"quantity",
"scenarioPrice"
]
}
workflow.run_black_scholes
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: no live data fetch. Prefer workflow.run_black_scholes_live instead when checking a real Deribit BTC/ETH 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. 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).
Parameters5
spot
number
required
Underlying spot price, USD
strike
number
required
Strike price, USD
daysToExpiry
number
required
Calendar days until expiry (can be fractional)
volatilityPct
number
required
Annualized implied volatility in percentage points, e.g. 60 for 60%
riskFreeRatePct
number
optional
Risk-free rate in percentage points. Default 0: standard crypto-options convention.
Raw schema
{
"type": "object",
"properties": {
"spot": {
"type": "number",
"description": "Underlying spot price, USD"
},
"strike": {
"type": "number",
"description": "Strike price, USD"
},
"daysToExpiry": {
"type": "number",
"description": "Calendar days until expiry (can be fractional)"
},
"volatilityPct": {
"type": "number",
"description": "Annualized implied volatility in percentage points, e.g. 60 for 60%"
},
"riskFreeRatePct": {
"type": "number",
"description": "Risk-free rate in percentage points. Default 0: standard crypto-options convention."
}
},
"required": [
"spot",
"strike",
"daysToExpiry",
"volatilityPct"
]
}
workflow.run_straddle_strangle
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. 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.
Parameters8
currency
string
optional
Underlying coin. Default BTC.
position
string
required
callStrike
number
required
Call leg strike, USD. Equal to putStrike for a straddle, higher for a strangle.
putStrike
number
required
Put leg strike, USD. Must be <= callStrike.
callPremiumCoin
number
required
Call leg premium per contract, in the base coin (e.g. 0.02 BTC)
putPremiumCoin
number
required
Put leg premium per contract, in the base coin
quantity
number
required
Number of straddle/strangle units (both legs sized equally)
scenarioPrice
number
required
Underlying price in USD to evaluate the payoff at
Raw schema
{
"type": "object",
"properties": {
"currency": {
"type": "string",
"enum": [
"BTC",
"ETH"
],
"description": "Underlying coin. Default BTC."
},
"position": {
"type": "string",
"enum": [
"long",
"short"
]
},
"callStrike": {
"type": "number",
"description": "Call leg strike, USD. Equal to putStrike for a straddle, higher for a strangle."
},
"putStrike": {
"type": "number",
"description": "Put leg strike, USD. Must be <= callStrike."
},
"callPremiumCoin": {
"type": "number",
"description": "Call leg premium per contract, in the base coin (e.g. 0.02 BTC)"
},
"putPremiumCoin": {
"type": "number",
"description": "Put leg premium per contract, in the base coin"
},
"quantity": {
"type": "number",
"description": "Number of straddle/strangle units (both legs sized equally)"
},
"scenarioPrice": {
"type": "number",
"description": "Underlying price in USD to evaluate the payoff at"
}
},
"required": [
"position",
"callStrike",
"putStrike",
"callPremiumCoin",
"putPremiumCoin",
"quantity",
"scenarioPrice"
]
}
workflow.run_covered_call_protective_put
Covered call (long the coin + short a call against it, for yield) or protective put (long the coin + long a put, for downside insurance) on a Deribit BTC/ETH position. Returns the standard annualized-yield metric (premium ÷ 1 coin, annualized by 365/daysToExpiry) up front: that number doesn't depend on any price scenario. Also returns the USD value of the combined position at a given scenario price: covered call caps upside at strike + premium×scenarioPrice (the premium's own coin-denominated value still scales with price, unlike a textbook USD-settled cap); protective put floors value at strike×(1−premium), which is the true minimum across every possible settlement price, not just an approximation. Use when user asks "what annualized yield do I get selling covered calls on my BTC?" or "how much does insuring my BTC with a put cost me?". Returns: staticYieldPct, annualizedYieldPct, valueAtScenarioUsd, breakevenPrice (covered_call only), floorValueUsd (protective_put only), vsHoldingUsd (vs. just holding the coin).
Parameters8
strategy
string
required
currency
string
optional
Underlying coin. Default BTC.
spotEntry
number
required
Price you acquired/value the underlying coin at, USD; used for the covered-call breakeven vs. cost basis
strike
number
required
Option strike, USD
premiumCoin
number
required
Premium received (covered_call) or paid (protective_put) per contract, in the base coin
daysToExpiry
number
required
Calendar days until expiry; used to annualize the yield/cost
quantity
number
required
Coin units held / contracts (1:1 covered)
scenarioPrice
number
required
Underlying price in USD to evaluate the combined position's value at
Raw schema
{
"type": "object",
"properties": {
"strategy": {
"type": "string",
"enum": [
"covered_call",
"protective_put"
]
},
"currency": {
"type": "string",
"enum": [
"BTC",
"ETH"
],
"description": "Underlying coin. Default BTC."
},
"spotEntry": {
"type": "number",
"description": "Price you acquired/value the underlying coin at, USD; used for the covered-call breakeven vs. cost basis"
},
"strike": {
"type": "number",
"description": "Option strike, USD"
},
"premiumCoin": {
"type": "number",
"description": "Premium received (covered_call) or paid (protective_put) per contract, in the base coin"
},
"daysToExpiry": {
"type": "number",
"description": "Calendar days until expiry; used to annualize the yield/cost"
},
"quantity": {
"type": "number",
"description": "Coin units held / contracts (1:1 covered)"
},
"scenarioPrice": {
"type": "number",
"description": "Underlying price in USD to evaluate the combined position's value at"
}
},
"required": [
"strategy",
"spotEntry",
"strike",
"premiumCoin",
"daysToExpiry",
"quantity",
"scenarioPrice"
]
}
workflow.run_spread_payoff
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. 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.
Parameters4
currency
string
optional
Underlying coin. Default BTC.
legs
array
required
Exactly 2 legs (same option type, opposite position - a vertical spread) or 4 legs (2 calls + 2 puts - an iron condor/butterfly). Each leg: { optionType: call|put, position: long|short, strike: number, premiumCoin: number }.
quantity
number
required
Number of spread/condor units
scenarioPrice
number
required
Underlying price in USD to evaluate the payoff at
Raw schema
{
"type": "object",
"properties": {
"currency": {
"type": "string",
"enum": [
"BTC",
"ETH"
],
"description": "Underlying coin. Default BTC."
},
"legs": {
"type": "array",
"minItems": 2,
"maxItems": 4,
"description": "Exactly 2 legs (same option type, opposite position - a vertical spread) or 4 legs (2 calls + 2 puts - an iron condor/butterfly). Each leg: { optionType: call|put, position: long|short, strike: number, premiumCoin: number }.",
"items": {
"type": "object",
"properties": {
"optionType": {
"type": "string",
"enum": [
"call",
"put"
]
},
"position": {
"type": "string",
"enum": [
"long",
"short"
]
},
"strike": {
"type": "number",
"description": "USD"
},
"premiumCoin": {
"type": "number",
"description": "Premium per contract, in the base coin"
}
},
"required": [
"optionType",
"position",
"strike",
"premiumCoin"
]
}
},
"quantity": {
"type": "number",
"description": "Number of spread/condor units"
},
"scenarioPrice": {
"type": "number",
"description": "Underlying price in USD to evaluate the payoff at"
}
},
"required": [
"legs",
"quantity",
"scenarioPrice"
]
}
workflow.run_implied_volatility
Solves for the volatility that makes Black-Scholes reproduce an observed option price (Newton-Raphson with a bisection fallback for cases where vega is too flat to converge, e.g. deep ITM/OTM or very short-dated). Checks the price against its no-arbitrage bounds first and refuses to solve (converged: false + error) rather than return a garbage number when the price is impossible for the given spot/strike/rate. Use when user asks "what IV does this option price imply?" or gives a market price and wants the volatility, not the reverse. Returns: impliedVolatilityPct, iterations, method (newton-raphson/bisection), converged, priceAtSolution.
Parameters6
optionType
string
required
spot
number
required
Underlying spot price, USD
strike
number
required
Strike price, USD
daysToExpiry
number
required
Calendar days until expiry (can be fractional)
riskFreeRatePct
number
optional
Risk-free rate in percentage points. Default 0: standard crypto-options convention.
targetPriceUsd
number
required
The observed option price, USD, to solve the implied volatility from
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. 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. Use when user asks "what should this up/down contract be worth?" or "what's the fair 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).
Parameters5
currentPrice
number
required
Current spot price of the coin, in USD.
referencePrice
number
required
The reference/pinned price the contract resolves against (the window's open price, or a stated strike).
minutesToClose
number
required
Minutes remaining until the window closes/settles.
volatilityPct
number
required
Annualized volatility, in percentage points (e.g. 50 for 50%). Required; no live source for this on these contracts.
riskFreeRatePct
number
optional
Risk-free rate in percentage points. Default 0: negligible for these short windows.
Raw schema
{
"type": "object",
"properties": {
"currentPrice": {
"type": "number",
"description": "Current spot price of the coin, in USD."
},
"referencePrice": {
"type": "number",
"description": "The reference/pinned price the contract resolves against (the window's open price, or a stated strike)."
},
"minutesToClose": {
"type": "number",
"description": "Minutes remaining until the window closes/settles."
},
"volatilityPct": {
"type": "number",
"description": "Annualized volatility, in percentage points (e.g. 50 for 50%). Required; no live source for this on these contracts."
},
"riskFreeRatePct": {
"type": "number",
"description": "Risk-free rate in percentage points. Default 0: negligible for these short windows."
}
},
"required": [
"currentPrice",
"referencePrice",
"minutesToClose",
"volatilityPct"
]
}
workflow.run_forex_pip_value
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. Prefer workflow.run_forex_pip_value_live instead when the account currency differs from the pair's quote currency. Use when user asks "what's 1 pip worth on X lots of EUR/USD?". Returns: pipSize, pipValueQuote, base, quote.
Parameters2
pair
string
required
Currency pair in BASE/QUOTE format, e.g. "EUR/USD"
units
number
required
Position size in base-currency units (1 standard lot = 100,000, mini = 10,000, micro = 1,000, nano = 100)
Raw schema
{
"type": "object",
"properties": {
"pair": {
"type": "string",
"description": "Currency pair in BASE/QUOTE format, e.g. \"EUR/USD\""
},
"units": {
"type": "number",
"description": "Position size in base-currency units (1 standard lot = 100,000, mini = 10,000, micro = 1,000, nano = 100)"
}
},
"required": [
"pair",
"units"
]
}
workflow.run_forex_margin_level
Free margin and margin level % from account equity and used margin: equity/usedMargin*100, the same stop-out proximity metric every forex platform shows. Returns null (not Infinity) when usedMargin is 0, meaning no open position. Use when user asks "how close am I to a margin call?" or "what's my free margin?". Returns: freeMargin, marginLevelPct.
Parameters2
equity
number
required
Account equity (balance + floating P&L)
usedMargin
number
required
Margin currently locked by open positions. 0 if none.
Raw schema
{
"type": "object",
"properties": {
"equity": {
"type": "number",
"description": "Account equity (balance + floating P&L)"
},
"usedMargin": {
"type": "number",
"description": "Margin currently locked by open positions. 0 if none."
}
},
"required": [
"equity",
"usedMargin"
]
}
workflow.run_forex_breakeven
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. Use when user asks "where's my true breakeven after spread and commission?". Returns: pipSize, commissionPips, totalCostPips, breakevenPrice.
Parameters5
pair
string
required
Currency pair in BASE/QUOTE format, e.g. "EUR/USD"
side
string
required
entryPrice
number
required
spreadPips
number
required
Spread at entry, in pips
commissionPerLotRoundTrip
number
optional
Round-trip commission per standard lot, in the pair's own quote currency. Default 0 (pure-spread broker model).
Raw schema
{
"type": "object",
"properties": {
"pair": {
"type": "string",
"description": "Currency pair in BASE/QUOTE format, e.g. \"EUR/USD\""
},
"side": {
"type": "string",
"enum": [
"long",
"short"
]
},
"entryPrice": {
"type": "number"
},
"spreadPips": {
"type": "number",
"description": "Spread at entry, in pips"
},
"commissionPerLotRoundTrip": {
"type": "number",
"description": "Round-trip commission per standard lot, in the pair's own quote currency. Default 0 (pure-spread broker model)."
}
},
"required": [
"pair",
"side",
"entryPrice",
"spreadPips"
]
}
workflow.run_forex_pnl
Profit or loss for a closed or hypothetical forex trade, in pips and in the pair's own quote currency, long or short. 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.
Parameters5
pair
string
required
Currency pair in BASE/QUOTE format, e.g. "EUR/USD"
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. Use when user asks "what's my risk/reward on this setup?". Returns: riskPips, rewardPips, validSetup, ratio.
Parameters5
pair
string
required
Currency pair in BASE/QUOTE format, e.g. "EUR/USD"
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. Use when user asks "what if price moves X pips in either direction?". Returns: scenarios[] (deltaPips, exitPrice, pnlQuote).
Parameters5
pair
string
required
Currency pair in BASE/QUOTE format, e.g. "EUR/USD"
side
string
required
entryPrice
number
required
units
number
required
Position size in base-currency units
deltasPips
array
required
Hypothetical price moves in pips, e.g. [-50, 0, 50]
Size-weighted average entry price across multiple forex fills: plain arithmetic mean, since forex has no coin-margined analog requiring the harmonic mean the crypto average_entry tool uses for inverse contracts. Use when user asks "what's my average entry after these fills?". Returns: totalUnits, totalCost, avgEntry.
Parameters2
pair
string
required
Currency pair in BASE/QUOTE format, e.g. "EUR/USD"
fills
array
required
Fills to average, each with a price and a size in base-currency units
Raw schema
{
"type": "object",
"properties": {
"pair": {
"type": "string",
"description": "Currency pair in BASE/QUOTE format, e.g. \"EUR/USD\""
},
"fills": {
"type": "array",
"items": {
"type": "object",
"properties": {
"price": {
"type": "number"
},
"units": {
"type": "number"
}
},
"required": [
"price",
"units"
]
},
"description": "Fills to average, each with a price and a size in base-currency units"
}
},
"required": [
"pair",
"fills"
]
}
workflow.run_forex_margin_required
Notional and margin required for a forex position, in the pair's own quote currency: no live FX rate needed. Never built for Phase 1 of this domain since a margin figure has no natural currency-neutral form the way pip value does. Prefer workflow.run_forex_margin_required_live instead when the account currency differs from the pair's quote currency. Use when user asks "how much margin do I need for X lots of EUR/USD at 50:1?". Returns: notionalQuote, marginQuote, base, quote.
Parameters4
pair
string
required
Currency pair in BASE/QUOTE format, e.g. "EUR/USD"
units
number
required
Position size in base-currency units
price
number
required
Entry or current price
leverage
number
required
Leverage multiplier, e.g. 50 for 50:1
Raw schema
{
"type": "object",
"properties": {
"pair": {
"type": "string",
"description": "Currency pair in BASE/QUOTE format, e.g. \"EUR/USD\""
},
"units": {
"type": "number",
"description": "Position size in base-currency units"
},
"price": {
"type": "number",
"description": "Entry or current price"
},
"leverage": {
"type": "number",
"description": "Leverage multiplier, e.g. 50 for 50:1"
}
},
"required": [
"pair",
"units",
"price",
"leverage"
]
}
workflow.run_forex_currency_converter
Converts an amount between currencies using a manually supplied rate: no live data fetch. Prefer workflow.run_forex_currency_converter_live instead to have the rate fetched automatically. Use when user already knows the exact rate they want applied. Returns: converted.
Parameters2
amount
number
required
Amount in the source currency
rate
number
required
Exchange rate to apply (1 unit of source currency = rate units of target currency)
Raw schema
{
"type": "object",
"properties": {
"amount": {
"type": "number",
"description": "Amount in the source currency"
},
"rate": {
"type": "number",
"description": "Exchange rate to apply (1 unit of source currency = rate units of target currency)"
}
},
"required": [
"amount",
"rate"
]
}
workflow.run_forex_swap_cost
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). Prefer workflow.run_forex_swap_cost_live instead when the account currency differs from the pair's quote currency. Use when user asks "how much will holding this position overnight cost me?". Returns: lots, totalSwapQuote, base, quote.
Parameters4
pair
string
required
Currency pair in BASE/QUOTE format, e.g. "EUR/USD"
units
number
required
Position size in base-currency units
swapPerLotPerNight
number
required
Swap rate per standard lot (100,000 units) per night, in the pair's quote currency. Negative = cost, positive = credit. Broker-set: get this from the user's broker platform, there is no live source for it.
nights
integer
required
Number of nights the position is held
Raw schema
{
"type": "object",
"properties": {
"pair": {
"type": "string",
"description": "Currency pair in BASE/QUOTE format, e.g. \"EUR/USD\""
},
"units": {
"type": "number",
"description": "Position size in base-currency units"
},
"swapPerLotPerNight": {
"type": "number",
"description": "Swap rate per standard lot (100,000 units) per night, in the pair's quote currency. Negative = cost, positive = credit. Broker-set: get this from the user's broker platform, there is no live source for it."
},
"nights": {
"type": "integer",
"description": "Number of nights the position is held"
}
},
"required": [
"pair",
"units",
"swapPerLotPerNight",
"nights"
]
}
workflow.run_forex_correlation
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. Prefer workflow.run_forex_correlation_live instead to have both series fetched automatically for two named pairs. Use when user already has two price series and wants their statistical relationship. Returns: n, correlation (-1 to 1), hedgeRatio.
Parameters2
rates1
array
required
First price series, chronological order, one price per date
rates2
array
required
Second price series, chronological order, same length and same dates as rates1
Raw schema
{
"type": "object",
"properties": {
"rates1": {
"type": "array",
"items": {
"type": "number"
},
"minItems": 5,
"description": "First price series, chronological order, one price per date"
},
"rates2": {
"type": "array",
"items": {
"type": "number"
},
"minItems": 5,
"description": "Second price series, chronological order, same length and same dates as rates1"
}
},
"required": [
"rates1",
"rates2"
]
}
workflow.run_var_cvar
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. 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).
Parameters4
returns
array
optional
Return series (e.g. daily % returns as decimals). Provide this OR mean+stdev, not both.
mean
number
optional
Mean return, if not supplying returns[] directly
stdev
number
optional
Standard deviation of returns, if not supplying returns[] directly
confidence
number
optional
Confidence level, 0-1 exclusive (default 0.95)
Raw schema
{
"type": "object",
"properties": {
"returns": {
"type": "array",
"items": {
"type": "number"
},
"minItems": 2,
"description": "Return series (e.g. daily % returns as decimals). Provide this OR mean+stdev, not both."
},
"mean": {
"type": "number",
"description": "Mean return, if not supplying returns[] directly"
},
"stdev": {
"type": "number",
"description": "Standard deviation of returns, if not supplying returns[] directly"
},
"confidence": {
"type": "number",
"description": "Confidence level, 0-1 exclusive (default 0.95)"
}
}
}
workflow.run_sharpe_stats
Sharpe ratio with the Lo (2002) serial-correlation-aware annualization correction (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. 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.
Parameters3
returns
array
required
Return series, one value per period
periods_per_year
number
optional
Periods per year for annualization (default 365, crypto convention - trades every day)
benchmark_sharpe
number
optional
Benchmark Sharpe ratio for the PSR test, same periodicity as returns (default 0)
Raw schema
{
"type": "object",
"properties": {
"returns": {
"type": "array",
"items": {
"type": "number"
},
"minItems": 3,
"description": "Return series, one value per period"
},
"periods_per_year": {
"type": "number",
"description": "Periods per year for annualization (default 365, crypto convention - trades every day)"
},
"benchmark_sharpe": {
"type": "number",
"description": "Benchmark Sharpe ratio for the PSR test, same periodicity as returns (default 0)"
}
},
"required": [
"returns"
]
}
workflow.run_hurst_exponent
Hurst exponent via rescaled-range (R/S) analysis: is this return/price series trending/persistent (H>0.5, a move tends to be followed by a move in the same direction), mean-reverting/anti-persistent (H<0.5), or consistent with a random walk (H~0.5)? Use when user asks "is this asset trending or mean-reverting?" or "does this series show long-range dependence?". Takes a return series, not raw price levels. Returns: hurst, interpretation (trending/mean_reverting/random_walk), window_sizes, rs_values.
Engle-Granger two-step cointegration test for a pair of price series: do they share a long-run equilibrium relationship (their spread is stationary/mean-reverting)? The standard pairs-trading signal test. Returns the cointegrating regression's hedge ratio (beta) and an ADF t-statistic on the residuals, compared against 1%/5%/10% critical values. Use when user asks "are these two assets cointegrated?" or "is this a valid pairs trade?". Returns: alpha, beta (hedge ratio), t_stat, critical_values, cointegrated (booleans at each significance level).
Parameters2
y
array
required
First price series (the dependent variable in the cointegrating regression)
x
array
required
Second price series, same length and dates as y
Raw schema
{
"type": "object",
"properties": {
"y": {
"type": "array",
"items": {
"type": "number"
},
"minItems": 20,
"description": "First price series (the dependent variable in the cointegrating regression)"
},
"x": {
"type": "array",
"items": {
"type": "number"
},
"minItems": 20,
"description": "Second price series, same length and dates as y"
}
},
"required": [
"y",
"x"
]
}
workflow.run_portfolio_tearsheet
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. 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.
Parameters4
returns
array
required
Return series, one value per period
periods_per_year
number
optional
Periods per year for annualization (default 365)
mar
number
optional
Minimum acceptable return for the Sortino ratio, same periodicity as returns (default 0)
benchmark_sharpe
number
optional
Benchmark Sharpe ratio for the PSR figure, same periodicity as returns (default 0)
Raw schema
{
"type": "object",
"properties": {
"returns": {
"type": "array",
"items": {
"type": "number"
},
"minItems": 3,
"description": "Return series, one value per period"
},
"periods_per_year": {
"type": "number",
"description": "Periods per year for annualization (default 365)"
},
"mar": {
"type": "number",
"description": "Minimum acceptable return for the Sortino ratio, same periodicity as returns (default 0)"
},
"benchmark_sharpe": {
"type": "number",
"description": "Benchmark Sharpe ratio for the PSR figure, same periodicity as returns (default 0)"
}
},
"required": [
"returns"
]
}
workflow.run_garch
GARCH(1,1) volatility model, fit by maximum likelihood on a return series: estimates omega/alpha/beta (the variance-persistence parameters) and forecasts next-period volatility. Use when user asks "what's my GARCH volatility forecast?" or "how persistent is volatility in this return series?". This is a backward-looking statistical fit, not a market prediction guarantee. Returns: mu, omega, alpha, beta, persistence (alpha+beta), unconditional_vol, forecast_vol, loglikelihood.
Parameters1
returns
array
required
Return series, one value per period, at least 50 values (GARCH needs real sample depth to identify persistence)
Raw schema
{
"type": "object",
"properties": {
"returns": {
"type": "array",
"items": {
"type": "number"
},
"minItems": 50,
"description": "Return series, one value per period, at least 50 values (GARCH needs real sample depth to identify persistence)"
}
},
"required": [
"returns"
]
}
workflow.run_risk_parity
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. 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.
Parameters3
returns
array
optional
One return series per asset (2+ assets, all series the same length). Provide this OR covariance, not both.
covariance
array
optional
Direct NxN covariance matrix, if not supplying returns[][] directly.
risk_budgets
array
optional
Target risk share per asset, one per asset (need not sum to 1, normalized internally). Default: equal (1/N each).
Raw schema
{
"type": "object",
"properties": {
"returns": {
"type": "array",
"items": {
"type": "array",
"items": {
"type": "number"
}
},
"description": "One return series per asset (2+ assets, all series the same length). Provide this OR covariance, not both."
},
"covariance": {
"type": "array",
"items": {
"type": "array",
"items": {
"type": "number"
}
},
"description": "Direct NxN covariance matrix, if not supplying returns[][] directly."
},
"risk_budgets": {
"type": "array",
"items": {
"type": "number"
},
"description": "Target risk share per asset, one per asset (need not sum to 1, normalized internally). Default: equal (1/N each)."
}
}
}
workflow.run_dsr
Deflated Sharpe Ratio (Bailey & Lopez de Prado): given how many strategy variants you tried (and how correlated they are), what Sharpe ratio would the *best of N* clear by luck alone, and does your actual strategy still clear that higher bar? Use when user asks "is my backtested Sharpe ratio real, or did I get lucky trying many variants?" or "how many independent trials does this really represent?". Provide either trial_sharpes[] (the N trials' own observed Sharpe ratios, most rigorous) or n_trials (+ optional avg_correlation to correct for correlated trials via Kish's design effect). Returns: expected_max_sharpe (the luck-alone threshold), dsr (probability your strategy's true Sharpe exceeds it, 0-1), n_trials_effective.
Parameters4
returns
array
required
The candidate strategy's own return series
trial_sharpes
array
optional
Observed Sharpe ratios of all N trials tried, if tracked. Takes priority over n_trials if both are given.
n_trials
number
optional
Number of strategy variants tried, if trial_sharpes were not tracked individually
avg_correlation
number
optional
Average pairwise correlation between trials, 0-1 (default 0 = independent). Only used with n_trials; lowers the effective trial count via Kish's design effect.
Raw schema
{
"type": "object",
"properties": {
"returns": {
"type": "array",
"items": {
"type": "number"
},
"minItems": 3,
"description": "The candidate strategy's own return series"
},
"trial_sharpes": {
"type": "array",
"items": {
"type": "number"
},
"minItems": 2,
"description": "Observed Sharpe ratios of all N trials tried, if tracked. Takes priority over n_trials if both are given."
},
"n_trials": {
"type": "number",
"description": "Number of strategy variants tried, if trial_sharpes were not tracked individually"
},
"avg_correlation": {
"type": "number",
"description": "Average pairwise correlation between trials, 0-1 (default 0 = independent). Only used with n_trials; lowers the effective trial count via Kish's design effect."
}
},
"required": [
"returns"
]
}
workflow.run_kelly_frontier
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). 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).
Parameters3
alpha
number
required
Fraction of starting capital, 0-1 exclusive (e.g. 0.5 = "ever falls to half my starting bankroll")
lambda_fraction
number
optional
Fraction of full Kelly being bet (1 = full Kelly, 0.5 = half Kelly). Provide this OR max_probability, not both.
max_probability
number
optional
Target ceiling on the ruin probability, 0-1 exclusive. Provide this to solve for the safe lambda_fraction instead of supplying it directly.
Raw schema
{
"type": "object",
"properties": {
"alpha": {
"type": "number",
"description": "Fraction of starting capital, 0-1 exclusive (e.g. 0.5 = \"ever falls to half my starting bankroll\")"
},
"lambda_fraction": {
"type": "number",
"description": "Fraction of full Kelly being bet (1 = full Kelly, 0.5 = half Kelly). Provide this OR max_probability, not both."
},
"max_probability": {
"type": "number",
"description": "Target ceiling on the ruin probability, 0-1 exclusive. Provide this to solve for the safe lambda_fraction instead of supplying it directly."
}
},
"required": [
"alpha"
]
}
workflow.run_unsmoothing
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?". 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.
Parameters1
returns
array
required
The observed (possibly smoothed) return series, at least 20 values
Extreme Value Theory tail risk (Peaks-Over-Threshold): fits a Generalized Pareto Distribution to the losses beyond a high threshold via Grimshaw's (1993) profile-likelihood MLE, then extrapolates VaR/Expected Shortfall at the requested confidence, without assuming a normal distribution. Use when user asks "what's my tail VaR without assuming normality?" or "how fat is my loss tail, really?". Complements workflow.run_var_cvar (parametric, normal-distribution VaR/CVaR) for exactly the fat-tailed-return case that assumption understates. threshold_percentile (default 90) sets which percentile of the loss distribution (losses = -returns) becomes the threshold u; confidence must be deep enough into the fitted tail (1-confidence < the threshold's own exceedance rate) or the call throws. Returns: threshold, n_exceedances, exceedance_rate, xi (GPD shape: 0=exponential tail, >0=heavy/fat tail, <0=bounded tail; values <= -1 are excluded from the fit domain as a known non-regular/unbounded-likelihood case, Smith 1985), beta (GPD scale), xi_asymptotically_normal (false when xi<=-0.5: the fit is still valid but the usual MLE confidence-interval theory doesn't apply, per that same Smith 1985 result), var, es (null when xi>=1, where Expected Shortfall is mathematically undefined).
Parameters3
returns
array
required
Return series, one value per period, at least 100 values (POT needs real sample depth in the tail)
threshold_percentile
number
optional
Percentile (0-100 exclusive) of the loss distribution used as the POT threshold u. Default 90.
confidence
number
optional
VaR/ES confidence level, 0-1 exclusive. Default 0.99. Must satisfy 1-confidence < the threshold's own exceedance rate.
Raw schema
{
"type": "object",
"properties": {
"returns": {
"type": "array",
"items": {
"type": "number"
},
"minItems": 100,
"description": "Return series, one value per period, at least 100 values (POT needs real sample depth in the tail)"
},
"threshold_percentile": {
"type": "number",
"description": "Percentile (0-100 exclusive) of the loss distribution used as the POT threshold u. Default 90."
},
"confidence": {
"type": "number",
"description": "VaR/ES confidence level, 0-1 exclusive. Default 0.99. Must satisfy 1-confidence < the threshold's own exceedance rate."
}
},
"required": [
"returns"
]
}
workflow.run_orderbook_impact
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. 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).
Parameters5
bids
array
required
Bid levels as [price, size_base] pairs, any order
asks
array
required
Ask levels as [price, size_base] pairs, any order
side
string
required
"buy" walks the asks, "sell" walks the bids
notional_usd
number
optional
Target notional to walk the book for. Provide this OR impact_budget_bps, not both.
impact_budget_bps
number
optional
Max acceptable impact in bps; solves for the largest notional within it. Provide this OR notional_usd, not both.
Raw schema
{
"type": "object",
"properties": {
"bids": {
"type": "array",
"items": {
"type": "array",
"items": {
"type": "number"
},
"minItems": 2,
"maxItems": 2
},
"description": "Bid levels as [price, size_base] pairs, any order"
},
"asks": {
"type": "array",
"items": {
"type": "array",
"items": {
"type": "number"
},
"minItems": 2,
"maxItems": 2
},
"description": "Ask levels as [price, size_base] pairs, any order"
},
"side": {
"type": "string",
"enum": [
"buy",
"sell"
],
"description": "\"buy\" walks the asks, \"sell\" walks the bids"
},
"notional_usd": {
"type": "number",
"description": "Target notional to walk the book for. Provide this OR impact_budget_bps, not both."
},
"impact_budget_bps": {
"type": "number",
"description": "Max acceptable impact in bps; solves for the largest notional within it. Provide this OR notional_usd, not both."
}
},
"required": [
"bids",
"asks",
"side"
]
}
workflow.run_open_analysis
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.
Parameters7
instrument
string
required
Symbol, e.g. BTCUSDT
venue
string
required
Exchange to fetch candles from when candles[] not supplied
session_date
string
required
Session date YYYY-MM-DD (UTC)
timeframe
string
optional
Candle timeframe (default 15m)
value_area_rule
number
optional
Value-area fraction 0.5–0.9 (default 0.70)
candles
array
optional
Optional OHLCV for the session; omit to fetch from venue (reproducible + 0 COGS when supplied)
prev_candles
array
optional
Optional OHLCV for the previous session
Raw schema
{
"type": "object",
"properties": {
"instrument": {
"type": "string",
"description": "Symbol, e.g. BTCUSDT"
},
"venue": {
"type": "string",
"enum": [
"binance",
"bybit"
],
"description": "Exchange to fetch candles from when candles[] not supplied"
},
"session_date": {
"type": "string",
"description": "Session date YYYY-MM-DD (UTC)"
},
"timeframe": {
"type": "string",
"enum": [
"1m",
"5m",
"15m",
"30m"
],
"description": "Candle timeframe (default 15m)"
},
"value_area_rule": {
"type": "number",
"description": "Value-area fraction 0.5–0.9 (default 0.70)"
},
"candles": {
"type": "array",
"description": "Optional OHLCV for the session; omit to fetch from venue (reproducible + 0 COGS when supplied)",
"items": {
"type": "object"
}
},
"prev_candles": {
"type": "array",
"description": "Optional OHLCV for the previous session",
"items": {
"type": "object"
}
}
},
"required": [
"instrument",
"venue",
"session_date"
]
}
workflow.run_session_structure
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.
Parameters7
instrument
string
required
Symbol, e.g. BTCUSDT
venue
string
required
Exchange to fetch candles from when candles[] not supplied
session_date
string
required
Session date YYYY-MM-DD (UTC)
timeframe
string
optional
Candle timeframe (default 15m)
value_area_rule
number
optional
Value-area fraction 0.5–0.9 (default 0.70)
candles
array
optional
Optional OHLCV for the session; omit to fetch from venue (reproducible + 0 COGS when supplied)
prev_candles
array
optional
Optional OHLCV for the previous session
Raw schema
{
"type": "object",
"properties": {
"instrument": {
"type": "string",
"description": "Symbol, e.g. BTCUSDT"
},
"venue": {
"type": "string",
"enum": [
"binance",
"bybit"
],
"description": "Exchange to fetch candles from when candles[] not supplied"
},
"session_date": {
"type": "string",
"description": "Session date YYYY-MM-DD (UTC)"
},
"timeframe": {
"type": "string",
"enum": [
"1m",
"5m",
"15m",
"30m"
],
"description": "Candle timeframe (default 15m)"
},
"value_area_rule": {
"type": "number",
"description": "Value-area fraction 0.5–0.9 (default 0.70)"
},
"candles": {
"type": "array",
"description": "Optional OHLCV for the session; omit to fetch from venue (reproducible + 0 COGS when supplied)",
"items": {
"type": "object"
}
},
"prev_candles": {
"type": "array",
"description": "Optional OHLCV for the previous session",
"items": {
"type": "object"
}
}
},
"required": [
"instrument",
"venue",
"session_date"
]
}
workflow.run_value_migration
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.
Parameters8
instrument
string
required
Symbol, e.g. BTCUSDT
venue
string
required
Exchange to fetch candles from when candles[] not supplied
session_date
string
required
Session date YYYY-MM-DD (UTC)
timeframe
string
optional
Candle timeframe (default 15m)
value_area_rule
number
optional
Value-area fraction 0.5–0.9 (default 0.70)
candles
array
optional
Optional OHLCV for the session; omit to fetch from venue (reproducible + 0 COGS when supplied)
prev_candles
array
optional
Optional OHLCV for the previous session
lookback_sessions
number
optional
Sessions to compare, 1–5 (default 1)
Raw schema
{
"type": "object",
"properties": {
"instrument": {
"type": "string",
"description": "Symbol, e.g. BTCUSDT"
},
"venue": {
"type": "string",
"enum": [
"binance",
"bybit"
],
"description": "Exchange to fetch candles from when candles[] not supplied"
},
"session_date": {
"type": "string",
"description": "Session date YYYY-MM-DD (UTC)"
},
"timeframe": {
"type": "string",
"enum": [
"1m",
"5m",
"15m",
"30m"
],
"description": "Candle timeframe (default 15m)"
},
"value_area_rule": {
"type": "number",
"description": "Value-area fraction 0.5–0.9 (default 0.70)"
},
"candles": {
"type": "array",
"description": "Optional OHLCV for the session; omit to fetch from venue (reproducible + 0 COGS when supplied)",
"items": {
"type": "object"
}
},
"prev_candles": {
"type": "array",
"description": "Optional OHLCV for the previous session",
"items": {
"type": "object"
}
},
"lookback_sessions": {
"type": "number",
"description": "Sessions to compare, 1–5 (default 1)"
}
},
"required": [
"instrument",
"venue",
"session_date"
]
}
workflow.run_breakout_acceptance
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.
Parameters8
instrument
string
required
Symbol, e.g. BTCUSDT
venue
string
required
Exchange to fetch candles from when candles[] not supplied
session_date
string
required
Session date YYYY-MM-DD (UTC)
timeframe
string
optional
Candle timeframe (default 15m)
value_area_rule
number
optional
Value-area fraction 0.5–0.9 (default 0.70)
candles
array
optional
Optional OHLCV for the session; omit to fetch from venue (reproducible + 0 COGS when supplied)
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. 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.
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. Use when user asks "how much slippage will I eat swapping X tokens?" or "what will I actually get if I sell N tokens?". Returns: outputAmount, priceImpactPct, effectivePrice, marketPriceUsd, liquidityUsd, routable (false + error if the size can't be routed at all).
Parameters3
mint
string
required
Solana mint address of the token being sold (base58)
amount
number
required
Amount of the token to swap, in human units (not raw base units)
outputAsset
string
optional
Asset to receive. Default USDC.
Raw schema
{
"type": "object",
"properties": {
"mint": {
"type": "string",
"description": "Solana mint address of the token being sold (base58)"
},
"amount": {
"type": "number",
"description": "Amount of the token to swap, in human units (not raw base units)"
},
"outputAsset": {
"type": "string",
"enum": [
"USDC",
"SOL"
],
"description": "Asset to receive. Default USDC."
}
},
"required": [
"mint",
"amount"
]
}
workflow.run_market_cap_comparison
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. 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).
Parameters5
tokenChain
string
optional
Chain of the token you hold. Default solana.
tokenMint
string
required
Address of the token you hold or are evaluating (base58 for Solana, 0x... for EVM chains)
compareToChain
string
optional
Chain of the comparison token. Default solana. Can differ from tokenChain.
compareToMint
string
required
Address of the token whose market cap to compare against
investmentUsd
number
required
Investment amount in USD
Raw schema
{
"type": "object",
"properties": {
"tokenChain": {
"type": "string",
"enum": [
"solana",
"ethereum",
"base",
"bsc",
"arbitrum",
"polygon"
],
"description": "Chain of the token you hold. Default solana."
},
"tokenMint": {
"type": "string",
"description": "Address of the token you hold or are evaluating (base58 for Solana, 0x... for EVM chains)"
},
"compareToChain": {
"type": "string",
"enum": [
"solana",
"ethereum",
"base",
"bsc",
"arbitrum",
"polygon"
],
"description": "Chain of the comparison token. Default solana. Can differ from tokenChain."
},
"compareToMint": {
"type": "string",
"description": "Address of the token whose market cap to compare against"
},
"investmentUsd": {
"type": "number",
"description": "Investment amount in USD"
}
},
"required": [
"tokenMint",
"compareToMint",
"investmentUsd"
]
}
workflow.run_impermanent_loss_live
Live variant of workflow.run_impermanent_loss: fetches each token's current live USD price (Solana or any of 5 EVM chains) and derives currentPrice as their ratio, instead of it being supplied manually. entryPrice stays a manual, historical input (a fact the caller must supply, not something a live quote should overwrite), same convention as every other live-capable tool in this product. Use when the caller has the pool's two token addresses but doesn't already know the current price ratio. Returns the same fields as workflow.run_impermanent_loss, plus currentPrice, baseSymbol, quoteSymbol, routable (false + error if either token's price can't be resolved).
Parameters10
mode
string
optional
Default full_range.
entryPrice
number
required
Base token's price in quote-token terms when liquidity was deposited (manual - a historical fact)
lowerPrice
number
optional
Range lower bound - required for concentrated mode
upperPrice
number
optional
Range upper bound - required for concentrated mode
depositValueUsd
number
optional
Optional: USD value deposited at entry
feesEarnedUsd
number
optional
Optional trading fees earned so far in USD (default 0)
baseChain
string
optional
Chain of the base (volatile) token. Default solana.
baseMint
string
required
Address of the base token
quoteChain
string
optional
Chain of the quote token. Default solana.
quoteMint
string
required
Address of the quote token
Raw schema
{
"type": "object",
"properties": {
"mode": {
"type": "string",
"enum": [
"full_range",
"concentrated"
],
"description": "Default full_range."
},
"entryPrice": {
"type": "number",
"description": "Base token's price in quote-token terms when liquidity was deposited (manual - a historical fact)"
},
"lowerPrice": {
"type": "number",
"description": "Range lower bound - required for concentrated mode"
},
"upperPrice": {
"type": "number",
"description": "Range upper bound - required for concentrated mode"
},
"depositValueUsd": {
"type": "number",
"description": "Optional: USD value deposited at entry"
},
"feesEarnedUsd": {
"type": "number",
"description": "Optional trading fees earned so far in USD (default 0)"
},
"baseChain": {
"type": "string",
"enum": [
"solana",
"ethereum",
"base",
"bsc",
"arbitrum",
"polygon"
],
"description": "Chain of the base (volatile) token. Default solana."
},
"baseMint": {
"type": "string",
"description": "Address of the base token"
},
"quoteChain": {
"type": "string",
"enum": [
"solana",
"ethereum",
"base",
"bsc",
"arbitrum",
"polygon"
],
"description": "Chain of the quote token. Default solana."
},
"quoteMint": {
"type": "string",
"description": "Address of the quote token"
}
},
"required": [
"entryPrice",
"baseMint",
"quoteMint"
]
}
workflow.run_wallet_flag_check
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. 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.
Parameters2
chain
string
optional
Chain of the wallet address. Default solana.
walletAddress
string
required
Wallet address (base58 for Solana, 0x... for EVM chains)
Converts a probability into decimal odds, American odds, and breakeven win rate: either from a manually supplied probability, or fetched live from Kalshi, Polymarket, ADI Predictstreet, Limitless, or Myriad (five independent crypto-price prediction market venues, all public keyless market data). 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). 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.
Parameters6
probability
number
optional
Probability as a decimal 0-1 (e.g. 0.35). Use this OR one of the live sources below, not both.
kalshiTicker
string
optional
A Kalshi market ticker (e.g. KXBTCY-27JAN0100-T149999.99) to fetch a live price from.
polymarketSlug
string
optional
A Polymarket market slug, from the market URL (e.g. will-bitcoin-reach-100k-in-september-2026), to fetch a live price from.
adiSymbol
string
optional
An ADI Predictstreet market symbol (e.g. BTC1D-20260920T0000). Currently always returns available:false; these contracts have no live trading volume yet.
limitlessSlug
string
optional
A Limitless Exchange market slug, from the market URL (e.g. btc-up-or-down-5-min-1790249100), to fetch a live price from. On-chain (Base), mostly short-duration (5min/15min/daily) crypto up/down contracts.
myriadSlug
string
optional
A Myriad Markets market slug, from the market URL (e.g. eth-at-three-digits-when-bitcoin-goes-below-50k), to fetch a live price from. On-chain (Abstract L2); not every market has a Yes/No outcome, some are multi-outcome ladders.
Raw schema
{
"type": "object",
"properties": {
"probability": {
"type": "number",
"description": "Probability as a decimal 0-1 (e.g. 0.35). Use this OR one of the live sources below, not both."
},
"kalshiTicker": {
"type": "string",
"description": "A Kalshi market ticker (e.g. KXBTCY-27JAN0100-T149999.99) to fetch a live price from."
},
"polymarketSlug": {
"type": "string",
"description": "A Polymarket market slug, from the market URL (e.g. will-bitcoin-reach-100k-in-september-2026), to fetch a live price from."
},
"adiSymbol": {
"type": "string",
"description": "An ADI Predictstreet market symbol (e.g. BTC1D-20260920T0000). Currently always returns available:false; these contracts have no live trading volume yet."
},
"limitlessSlug": {
"type": "string",
"description": "A Limitless Exchange market slug, from the market URL (e.g. btc-up-or-down-5-min-1790249100), to fetch a live price from. On-chain (Base), mostly short-duration (5min/15min/daily) crypto up/down contracts."
},
"myriadSlug": {
"type": "string",
"description": "A Myriad Markets market slug, from the market URL (e.g. eth-at-three-digits-when-bitcoin-goes-below-50k), to fetch a live price from. On-chain (Abstract L2); not every market has a Yes/No outcome, some are multi-outcome ladders."
}
},
"required": []
}
workflow.run_spread_reader
Reads the same real-world bet's live price from 2-5 prediction-market venues at once (Kalshi, Polymarket, ADI Predictstreet, Limitless, Myriad) and reports the spread between the cheapest and most expensive. 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. Use when user asks "is this bet priced differently on Kalshi vs Polymarket?" or "which venue has the best price on this?". Returns: quotes[] (venue, identifier, label, probabilityPct, available, error), availableCount, cheapestVenue, mostExpensiveVenue, spreadPct (percentage points, null if fewer than 2 quotes resolved).
Parameters1
quotes
array
required
One entry per venue you want to compare: 2 to 5 total. Each must genuinely be the same real-world bet; this tool does not verify that for you.
Raw schema
{
"type": "object",
"properties": {
"quotes": {
"type": "array",
"minItems": 2,
"maxItems": 5,
"items": {
"type": "object",
"properties": {
"venue": {
"type": "string",
"enum": [
"kalshi",
"polymarket",
"adi",
"limitless",
"myriad"
]
},
"identifier": {
"type": "string",
"description": "Kalshi ticker, Polymarket slug, ADI Predictstreet symbol, Limitless slug, or Myriad slug, matching the venue field."
}
},
"required": [
"venue",
"identifier"
]
},
"description": "One entry per venue you want to compare: 2 to 5 total. Each must genuinely be the same real-world bet; this tool does not verify that for you."
}
},
"required": [
"quotes"
]
}
workflow.run_cross_venue_arbitrage
Checks 2-5 quotes for the SAME real-world binary bet across venues (or manually-supplied probabilities) for a guaranteed, direction-independent arbitrage: buy "Yes" at whichever venue quotes it cheapest, buy "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, guaranteed profit and ROI for a given stake, and which side to buy where. feePctPerLeg is an optional per-leg trading-fee rate that can and does erase a real-looking spread - reported honestly via isArbitrage rather than always showing a positive number. Use when user asks "can I arbitrage this bet across venues?" or "is there a risk-free profit here?". The caller asserts the venues quote the same bet; this tool does not verify that.
Parameters4
quotes
array
optional
Live mode: one entry per venue, 2-5 total. Provide this OR manualProbabilitiesPct, not both.
manualProbabilitiesPct
array
optional
Manual mode: 2-5 probabilities (0.01-99.99) already known for the same bet across different venues, when you don't want a live fetch. Provide this OR quotes, not both.
stakeUsd
number
required
Total capital to deploy across both legs
feePctPerLeg
number
optional
Optional per-leg trading-fee rate, e.g. 0.02 for 2% (default 0)
Raw schema
{
"type": "object",
"properties": {
"quotes": {
"type": "array",
"minItems": 2,
"maxItems": 5,
"items": {
"type": "object",
"properties": {
"venue": {
"type": "string",
"enum": [
"kalshi",
"polymarket",
"adi",
"limitless",
"myriad"
]
},
"identifier": {
"type": "string",
"description": "Kalshi ticker, Polymarket slug, ADI Predictstreet symbol, Limitless slug, or Myriad slug, matching the venue field."
}
},
"required": [
"venue",
"identifier"
]
},
"description": "Live mode: one entry per venue, 2-5 total. Provide this OR manualProbabilitiesPct, not both."
},
"manualProbabilitiesPct": {
"type": "array",
"minItems": 2,
"maxItems": 5,
"items": {
"type": "number"
},
"description": "Manual mode: 2-5 probabilities (0.01-99.99) already known for the same bet across different venues, when you don't want a live fetch. Provide this OR quotes, not both."
},
"stakeUsd": {
"type": "number",
"description": "Total capital to deploy across both legs"
},
"feePctPerLeg": {
"type": "number",
"description": "Optional per-leg trading-fee rate, e.g. 0.02 for 2% (default 0)"
}
},
"required": [
"stakeUsd"
]
}
workflow.run_market_implied_odds
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. 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).
Parameters2
coin
string
optional
Which coin's year-end ladder to read. Default BTC.
thresholdUsd
number
optional
Optional price threshold: returns the probability of ending the year at or above the nearest real bucket boundary at or below this value.
Raw schema
{
"type": "object",
"properties": {
"coin": {
"type": "string",
"enum": [
"BTC",
"ETH"
],
"description": "Which coin's year-end ladder to read. Default BTC."
},
"thresholdUsd": {
"type": "number",
"description": "Optional price threshold: returns the probability of ending the year at or above the nearest real bucket boundary at or below this value."
}
},
"required": []
}
workflow.run_black_scholes_live
Black-Scholes theoretical price and Greeks for a REAL, live Deribit BTC/ETH option instrument: pulls that instrument's own spot, strike, days to expiry, and implied volatility from Deribit, then reports how far Deribit'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. Use when user gives a specific instrument name (e.g. "BTC-27FEB27-90000-C") and asks "is this option fairly priced?" or "what are the Greeks on this contract?". Returns everything workflow.run_black_scholes does, plus instrumentName, currency, optionType, deribitMarkPriceCoin, deribitMarkIvPct, bsPriceCoin, priceDiscrepancyPct, available (false + error if the instrument name doesn't resolve).
Parameters2
instrumentName
string
required
Exact Deribit instrument name, e.g. BTC-27FEB27-90000-C. Get one from Deribit's options chain; this tool does not browse the chain, it prices one named instrument.
riskFreeRatePct
number
optional
Risk-free rate in percentage points. Default 0: standard crypto-options convention.
Raw schema
{
"type": "object",
"properties": {
"instrumentName": {
"type": "string",
"description": "Exact Deribit instrument name, e.g. BTC-27FEB27-90000-C. Get one from Deribit's options chain; this tool does not browse the chain, it prices one named instrument."
},
"riskFreeRatePct": {
"type": "number",
"description": "Risk-free rate in percentage points. Default 0: standard crypto-options convention."
}
},
"required": [
"instrumentName"
]
}
workflow.run_forex_pip_value_live
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). 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).
Parameters3
pair
string
required
Currency pair in BASE/QUOTE format, e.g. "EUR/USD"
units
number
required
Position size in base-currency units
accountCurrency
string
required
3-letter account currency code, e.g. "GBP"
Raw schema
{
"type": "object",
"properties": {
"pair": {
"type": "string",
"description": "Currency pair in BASE/QUOTE format, e.g. \"EUR/USD\""
},
"units": {
"type": "number",
"description": "Position size in base-currency units"
},
"accountCurrency": {
"type": "string",
"description": "3-letter account currency code, e.g. \"GBP\""
}
},
"required": [
"pair",
"units",
"accountCurrency"
]
}
workflow.run_forex_margin_required_live
Notional and margin required for a forex position, converted to a given account currency via a live FX rate (same TrueFX/frankfurter.app source as workflow.run_forex_pip_value_live). Use when user asks "how much margin do I need in my account currency?" and the account currency differs from the pair's own quote currency. Returns everything workflow.run_forex_margin_required does, plus accountCurrency, notionalAccount, marginAccount, fxRate, fxSource, available (false + error if no rate could be found).
Parameters5
pair
string
required
Currency pair in BASE/QUOTE format, e.g. "EUR/USD"
units
number
required
Position size in base-currency units
price
number
required
Entry or current price
leverage
number
required
Leverage multiplier, e.g. 50 for 50:1
accountCurrency
string
required
3-letter account currency code, e.g. "GBP"
Raw schema
{
"type": "object",
"properties": {
"pair": {
"type": "string",
"description": "Currency pair in BASE/QUOTE format, e.g. \"EUR/USD\""
},
"units": {
"type": "number",
"description": "Position size in base-currency units"
},
"price": {
"type": "number",
"description": "Entry or current price"
},
"leverage": {
"type": "number",
"description": "Leverage multiplier, e.g. 50 for 50:1"
},
"accountCurrency": {
"type": "string",
"description": "3-letter account currency code, e.g. \"GBP\""
}
},
"required": [
"pair",
"units",
"price",
"leverage",
"accountCurrency"
]
}
workflow.run_forex_position_size_live
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. 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).
Parameters5
pair
string
required
Currency pair in BASE/QUOTE format, e.g. "EUR/USD"
Converts an amount between currencies using a live FX rate: TrueFX for its 10 quoted majors (genuinely live tick data), frankfurter.app daily ECB reference rate as the fallback for every other currency pair (30 total). Use when user asks "what's $X worth in EUR?" or any currency conversion where the rate itself isn't already known. Returns: converted, rate, source (truefx/frankfurter/identity), asOf, available (false + error if no rate could be found for that pair).
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. 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).
Parameters5
pair
string
required
Currency pair in BASE/QUOTE format, e.g. "EUR/USD"
units
number
required
Position size in base-currency units
swapPerLotPerNight
number
required
Swap rate per standard lot per night, in the pair's quote currency. Negative = cost, positive = credit.
nights
integer
required
Number of nights the position is held
accountCurrency
string
required
3-letter account currency code, e.g. "GBP"
Raw schema
{
"type": "object",
"properties": {
"pair": {
"type": "string",
"description": "Currency pair in BASE/QUOTE format, e.g. \"EUR/USD\""
},
"units": {
"type": "number",
"description": "Position size in base-currency units"
},
"swapPerLotPerNight": {
"type": "number",
"description": "Swap rate per standard lot per night, in the pair's quote currency. Negative = cost, positive = credit."
},
"nights": {
"type": "integer",
"description": "Number of nights the position is held"
},
"accountCurrency": {
"type": "string",
"description": "3-letter account currency code, e.g. \"GBP\""
}
},
"required": [
"pair",
"units",
"swapPerLotPerNight",
"nights",
"accountCurrency"
]
}
workflow.run_forex_correlation_live
Correlation coefficient and minimum-variance hedge ratio between two forex pairs, fetched live: historical daily rates for both pairs over the given lookback window (frankfurter.app's daily ECB reference time series, business days only), aligned by matching date, computed on daily % returns. hedgeRatio follows Hull's standard futures-hedging formula: "how many units of pair2 per unit of pair1 minimizes the combined position's variance." Use when user asks "how correlated are EUR/USD and GBP/USD?" or "what hedge ratio should I use between these two pairs?". Returns: n (overlapping trading days used), correlation (-1 to 1), hedgeRatio, available (false + error if either pair has no data, or too few dates overlap).
Parameters3
pair1
string
required
First currency pair in BASE/QUOTE format, e.g. "EUR/USD"
pair2
string
required
Second currency pair in BASE/QUOTE format, e.g. "GBP/USD"
days
integer
optional
Calendar days to look back, 14-365. Default 30. Business-day-only data means fewer actual points than this number.
Raw schema
{
"type": "object",
"properties": {
"pair1": {
"type": "string",
"description": "First currency pair in BASE/QUOTE format, e.g. \"EUR/USD\""
},
"pair2": {
"type": "string",
"description": "Second currency pair in BASE/QUOTE format, e.g. \"GBP/USD\""
},
"days": {
"type": "integer",
"description": "Calendar days to look back, 14-365. Default 30. Business-day-only data means fewer actual points than this number."
}
},
"required": [
"pair1",
"pair2"
]
}
workflow.run_prediction_market_edge
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 zero recommended stake whenever your probability doesn't exceed the market's price: no edge, no bet. Use when user asks "does this bet have edge?" or "how much should I stake given my probability estimate vs the market's?". Provide exactly one of marketProbabilityPct/kalshiTicker/limitlessSlug/myriadSlug. Returns: edgePct, evPerDollarStaked, fullKellyFraction, cappedKellyFraction, recommendedStakeUsd, verdict (skip_this_one/think_twice/worth_the_risk/take_it).
Parameters7
yourProbabilityPct
number
required
Your own probability estimate, 0.01-99.99
marketProbabilityPct
number
optional
The market's probability (price), 0.01-99.99. Use this OR one of the live sources below, not both.
kalshiTicker
string
optional
A Kalshi market ticker to fetch the market probability from live instead of supplying it manually.
limitlessSlug
string
optional
A Limitless Exchange market slug to fetch the market probability from live instead of supplying it manually.
myriadSlug
string
optional
A Myriad Markets market slug to fetch the market probability from live instead of supplying it manually. Not every market has a Yes/No outcome.
bankrollUsd
number
required
Bankroll available for this bet, in USD
kellyFractionCap
number
optional
Fraction of full Kelly to actually stake, 0.01-1. Default 0.25 (quarter-Kelly).
Raw schema
{
"type": "object",
"properties": {
"yourProbabilityPct": {
"type": "number",
"description": "Your own probability estimate, 0.01-99.99"
},
"marketProbabilityPct": {
"type": "number",
"description": "The market's probability (price), 0.01-99.99. Use this OR one of the live sources below, not both."
},
"kalshiTicker": {
"type": "string",
"description": "A Kalshi market ticker to fetch the market probability from live instead of supplying it manually."
},
"limitlessSlug": {
"type": "string",
"description": "A Limitless Exchange market slug to fetch the market probability from live instead of supplying it manually."
},
"myriadSlug": {
"type": "string",
"description": "A Myriad Markets market slug to fetch the market probability from live instead of supplying it manually. Not every market has a Yes/No outcome."
},
"bankrollUsd": {
"type": "number",
"description": "Bankroll available for this bet, in USD"
},
"kellyFractionCap": {
"type": "number",
"description": "Fraction of full Kelly to actually stake, 0.01-1. Default 0.25 (quarter-Kelly)."
}
},
"required": [
"yourProbabilityPct",
"bankrollUsd"
]
}
system.verify
Run the full regression suite: 42 canonical test vectors (linear and inverse/coin-margined) across all 12 calculators, and return a pass/fail report with counts and timestamp. Call this before using results in production workflows to confirm the computation layer is operating correctly.
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.
An LLM guesses trading maths. This server computes it: the same inputs always return the same numbers, every
result carries a signature you can check, and the core formulas are tested against public vectors (live count in the
badge above).
code
Your question MCP tool call Result
+------------------+ +---------------------------+ +---------------------------+
| "Risk $200 on | ► | workflow.run_forex_ | ► | 0.67 lots, plus an ECDSA |
| EUR/USD with a | | position_size_live | | P-256 signature you can |
| 30 pip stop" | | (deterministic maths) | | verify offline |
+------------------+ +---------------------------+ +---------------------------+
Ask Claude, Cursor or any MCP client trade questions and get exact numbers back, not guesses:
"What should a BTC call at a $90k strike, 30 days out, with 55% implied volatility be worth?"
"How many lots of EUR/USD should I trade to risk $200 with a 30-pip stop?"
"What's my 95% Value at Risk on this monthly return series?"
"What's my PnL if I buy 0.5 BTC at $80k and sell at $95k with 5x leverage?"
What it covers (75 tools)
Domain
Examples
Options
Black-Scholes price and Greeks (manual, or checked live against a Deribit BTC/ETH option), payoff and breakeven, straddle and strangle, vertical spreads, covered call and protective put, implied volatility
Forex
Position size from a risk amount, pip value, margin, swap cost, currency conversion, pair correlation, with live-rate variants for the account currency
Risk and statistics
VaR and CVaR, Sharpe with the Lo 2002 correction, Deflated Sharpe, Kelly frontier, GARCH(1,1), risk parity, Hurst exponent, cointegration, portfolio tearsheet, EVT tail risk
Prediction markets
Odds and vig, market-implied odds, edge sizing, spread and arbitrage checks across Kalshi, Polymarket, Limitless and Myriad
On-chain
Solana token and wallet checks, swap price impact, pump.fun bonding curve, impermanent loss
Crypto futures
PnL, liquidation price, breakeven, funding cost, position size, risk/reward, linear and coin-margined contracts
Access via MCP (Claude Desktop, Cursor, VS Code and other clients) or a plain HTTP POST to the MCP endpoint. No
signup. The server is remote, so nothing to install beyond a one-line client config; only the Claude Desktop bridge
below needs Node.js 18 or newer.
For coding agents that support the skills.sh ecosystem (Claude Code, Cursor,
GitHub Copilot, and others) - installs a SKILL.md that teaches the agent when to reach for these
tools instead of estimating trade math itself:
After connecting, just ask naturally: the AI picks the right tool automatically:
Options payoff
"What does my BTC call payoff at $90,000? Strike $85,000, premium 0.02 BTC, long 1 contract."
Black-Scholes / IV check
"Is Deribit's BTC-27FEB27-90000-C fairly priced right now?"
Covered call yield
"I hold BTC bought at $80,000. What annualized yield do I get selling a $85,000-strike call for 0.02 BTC, 30 days out?"
Forex pip value
"What's a pip worth on 2 lots of EUR/USD, in my USD account?"
Forex position size
"How many lots should I trade to risk $200 on EUR/USD with a 30-pip stop?"
Forex margin level
"My equity is $5,000 and used margin is $1,800. How close am I to a margin call?"
Value at Risk
"What's my 95% Value at Risk and expected shortfall on this monthly return series? [paste returns]"
Sharpe ratio
"What's the Sharpe ratio of these monthly returns, corrected for autocorrelation?"
Cointegration
"Are these two price series cointegrated? Is there a pairs trade?"
Odds converter
"What odds does a 35% probability work out to?"
Market-implied odds
"What does the market think BTC will be worth by year end?"
Prediction market edge
"I think this event is 60% likely but the market prices it at 40%. Should I bet, and how much with a $10k bankroll?"
Token safety check
"Is this Solana token a rug pull risk? Mint: DezXAZ8z7PnrnRJjz3wXBoRgixCa6xjnB7YaB1pPB263"
Swap price impact
"How much slippage will I eat swapping 50,000,000 BONK to USDC?"
Bonding curve
"How many tokens do I get buying with 1 SOL on a pump.fun curve that's already raised 20 SOL?"
Market cap comparison
"If I put $1,000 into BONK and it reaches JUP's market cap, what's it worth?"
Wallet flag check
"Is this wallet address flagged for anything? [address]" (Solana or EVM)
Trade P&L
"I bought 0.5 BTC at $80,000 and want to sell at $95,000 with 5x leverage. What's my net profit after fees?"
Position sizing
"I have a $10,000 account and want to risk 1% going long BTC at $83,000 with a stop at $81,000. How many coins should I buy?"
Liquidation check
"Long ETH at $3,200 with 10x leverage, where do I get liquidated?"
Full pre-trade check
"Analyze this setup: long BTC at $83,000, stop $81,000, target $90,000, $10k account, 1% risk, 5x leverage. Is it worth taking?"
Funding cost
"I'm holding 0.5 BTC long on Bybit at $83,000 with 0.01% funding rate. How much will funding cost me over 3 days?"
Carry trade
"Is this carry trade worth it? Long on Bybit at 0.01% funding, short on Binance at 0.05%, $50k notional, 30 days."
DCA average entry
"I bought BTC at $78k (0.2 BTC), $80k (0.3 BTC), and $82k (0.1 BTC). What's my average entry and breakeven?"
Scale-out plan
"I'm long 1 BTC from $80k. I want to close 30% at $88k, 40% at $92k, 30% at $96k. What's my total P&L?"
Tools (75)
Tool naming follows the workflow.run_* / primitive.* / system.* namespace convention.
Old flat names (pnl, liquidation, etc.) are accepted for backward compatibility. All tools are
free via MCP, no signup; 100 calls/day anonymously, 200/day with a free API key.
system.verify proves the formulas are correct. It doesn't prove the specific response you got
wasn't altered by a proxy, cache, or MITM in between. Every tools/call result carries a second
content block signed with ECDSA P-256, plus X-TradingCalc-Signature/Kid/Signed-At headers.
Call system.pubkey (or GET /api/mcp/pubkey) for the public key (PEM + JWK) and the canonical
string format needed to verify offline, no callback required.
Once a day the verification state is also signed and its SHA-256 is written to Solana mainnet in a Memo transaction (tcalc1 {date} {hash}), each record carrying the hash of the day before. Read the records at GET https://tradingcalc.io/api/anchors; the latest record and how to verify it yourself are at tradingcalc.io/verification.
Use Cases
Options and forex desks: price an option, size a forex position, or check margin level in one exact call
Quant research: Sharpe, VaR, cointegration and drawdown statistics from a return series, cross-checked against reference libraries
Trading bots: check liquidation price before every trade
AI agents: deterministic risk calculations without hallucination risk
LLMs asked directly give plausible but potentially wrong numbers. TradingCalc MCP returns exact calculations: same inputs always produce the same outputs. No hallucination risk for financial data.
Risk Agent Wrapper
examples/risk-agent-wrapper.ts: a drop-in TypeScript wrapper for risk-gated trade execution.
Integrates with any agent framework (ElizaOS, CrewAI, AutoGen, Hummingbot, Freqtrade).
