io.github.SKalinin909/tradingcalc

Official19 tools

by SKalinin909

TradingCalc MCP — Crypto Futures Math

Crypto futures math: PnL, liquidation, position sizing, carry trade. 19 tools. Not AI estimates.

Crypto futures calculations for PnL, liquidation, position sizing, and carry trades.

Captured live from the server via tools/list.

workflow.run_pnl_planning

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 (%).

Parameters (6)

sidestringrequired
Trade direction
entryPricenumberrequired
Entry price (positive)
exitPricenumberrequired
Exit price (positive)
sizenumberrequired
Position size in base asset
feeOpenPctnumber
Opening fee as fraction, e.g. 0.0002 = 0.02%
feeClosePctnumber
Closing fee as fraction

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).

Parameters (4)

sidestringrequired
entryPricenumberrequired
Entry price (positive)
leveragenumberrequired
Leverage multiplier, e.g. 10 for 10x
mmrnumber
Maintenance margin rate, default 0.005 (0.5%)

workflow.run_breakeven_planning

Calculate the break-even exit price that covers all trading fees. Use when user asks "what price do I need to just break even?" Returns: breakevenPrice, totalFees.

Parameters (5)

sidestringrequired
entryPricenumberrequired
Entry price (positive)
sizeBasenumberrequired
Position size in base asset
feeOpenPctnumber
Opening fee fraction, default 0.0002
feeClosePctnumber
Closing fee fraction, default 0.0005

workflow.run_position_sizing

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.

Parameters (7)

sidestringrequired
entryPricenumberrequired
Entry price
stopLossnumberrequired
Stop-loss price
riskUsdtnumberrequired
Maximum acceptable loss in USDT
leveragenumber
Leverage, default 1
feeOpenPctnumber
Opening fee fraction, default 0.0002
feeClosePctnumber
Closing fee fraction, default 0.0005

workflow.run_funding_cost

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.

Parameters (5)

sidestringrequired
sizeBasenumberrequired
Position size in base asset
entryPricenumberrequired
Entry price
fundingRatenumberrequired
Funding rate per 8h period as fraction, e.g. 0.0001
daysnumberrequired
Number of days to hold

primitive.average_entry

Calculate the weighted average entry price from multiple buy/sell fills (DCA). Use when user has filled at multiple prices and asks "what's my average entry?" Returns: averagePrice, totalSize, totalCost.

Parameters (3)

symbolstringrequired
Trading pair symbol, e.g. BTCUSDT
exchangeCodestring
Exchange identifier (optional)
inputobjectrequired

workflow.run_exit_target

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.

Parameters (8)

sidestringrequired
entryPricenumberrequired
Entry price
leveragenumberrequired
Leverage multiplier
sizeBasenumberrequired
Position size in base asset
targetModestringrequired
"pnl" = target in USDT, "roe" = target in %
targetValuenumberrequired
Target value (USDT or %)
feeOpenPctnumber
Opening fee fraction, default 0.0002
feeClosePctnumber
Closing fee fraction, default 0.0005

workflow.run_scenario_planning

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 }.

Parameters (6)

sidestringrequired
entryPricenumberrequired
Entry price
sizenumberrequired
Position size in base asset
deltasPctarrayrequired
List of price change percentages, e.g. [-10, -5, 0, 5, 10]
feeOpenPctnumber
Opening fee fraction
feeClosePctnumber
Closing fee fraction

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.

Parameters (4)

accountSizenumberrequired
Total account size in USDT
maxDrawdownPctnumberrequired
Maximum acceptable drawdown as percentage, e.g. 10 for 10%
volatilityPctnumberrequired
Expected daily price volatility as percentage, e.g. 3 for 3%
mmrnumber
Maintenance margin rate, default 0.005 (0.5%)

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.

Parameters (4)

spotSizenumberrequired
Spot position value in USDT
hedgeRationumber
Percentage of spot to hedge, e.g. 100 for full hedge, 50 for half. Default 100.
leveragenumber
Leverage on the perp short. Default 1.
fundingRatePctnumber
Current 8h funding rate as percentage, e.g. 0.01. Used for cost estimate.

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. Use when user asks "is this funding arb worth it?" or "how many days to break even on transfer fees?". Returns: netProfitUsdt, annualizedYieldPct, breakevenDays.

Parameters (6)

positionSizenumberrequired
Position size in USDT
longFundingRatenumberrequired
Funding rate on long side (% per interval, positive = you pay)
shortFundingRatenumberrequired
Funding rate on short side (% per interval, positive = you receive)
transferFeePctnumber
One-time transfer/setup fee as percentage, e.g. 0.1 for 0.1%
durationDaysnumberrequired
Holding period in days
intervalHoursnumber
Funding interval: 8 (standard) or 1 (Hyperliquid)

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.

Parameters (5)

initialCapitalnumberrequired
Starting capital in USDT
fundingRatePctnumberrequired
Funding rate per interval as percentage, e.g. 0.01 for 0.01%
intervalHoursnumber
Funding interval: 8 (standard) or 1 (Hyperliquid)
durationDaysnumberrequired
Number of days to project
reinvestPctnumber
Percentage of earnings reinvested each interval. 100 = full compounding, 0 = no reinvestment. Default 100.

workflow.run_pre_trade_check

Full pre-trade decision card: orchestrates position sizing, breakeven, liquidation, and funding cost in one call. 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. Returns: positionSize, breakeven, liquidationPrice, fundingCost, overnightBreakevenShift, verdict.

Parameters (13)

exchangestring
Exchange code, e.g. "binance" or "bybit". Used to fetch live funding rate if funding_rate is omitted.
symbolstring
Perpetual symbol, e.g. "BTCUSDT".
sidestringrequired
entry_pricenumberrequired
Entry price (positive)
stop_lossnumberrequired
Stop-loss price (positive)
account_balancenumberrequired
Total account balance in USDT
risk_pctnumberrequired
Risk as % of balance, e.g. 1.0 = 1%
leveragenumberrequired
Leverage multiplier
funding_ratenumber
Funding rate per 8h as decimal, e.g. 0.0001. If omitted, fetched live from exchange.
hold_hoursnumber
Expected hold time in hours for overnight shift calc. Default 8.
fee_open_pctnumber
Opening fee fraction, default 0.0002
fee_close_pctnumber
Closing fee fraction, default 0.0005
mmrnumber
Maintenance margin rate, default 0.005

workflow.run_risk_reward

Full risk:reward analysis — the single best tool when user describes a trade with entry, stop, and target. 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. Use when user asks "is this trade worth taking?" or "what's my risk reward on this setup?".

Parameters (10)

sidestringrequired
entry_pricenumberrequired
Entry price
stop_lossnumberrequired
Stop-loss price
take_profitnumberrequired
Take-profit price
account_balancenumberrequired
Account balance in USDT
risk_pctnumberrequired
Max risk as % of account
leveragenumberrequired
Leverage multiplier
fee_open_pctnumber
Open fee rate (default 0.0002)
fee_close_pctnumber
Close fee rate (default 0.0005)
mmrnumber
Maintenance margin rate (default 0.005)

workflow.run_dca_entry

DCA entry planner: weighted average entry price, breakeven, and per-level contribution from multiple fill prices and sizes. 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.

Parameters (4)

sidestringrequired
entriesarrayrequired
fee_open_pctnumber
Open fee rate (default 0.0002)
fee_close_pctnumber
Close fee rate (default 0.0005)

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.

Parameters (6)

sidestringrequired
entry_pricenumberrequired
Entry price
total_sizenumberrequired
Total position size in base currency
exitsarrayrequired
fee_open_pctnumber
Open fee rate (default 0.0002)
fee_close_pctnumber
Close fee rate (default 0.0005)

workflow.run_carry_trade

Delta-neutral carry trade (funding arbitrage) analysis. 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).

Parameters (6)

notionalnumberrequired
Position notional in USDT
funding_rate_longnumberrequired
Funding rate on long exchange per interval (decimal)
funding_rate_shortnumberrequired
Funding rate on short exchange per interval (decimal)
transfer_fee_pctnumber
One-way transfer fee % (default 0.1)
hold_daysnumberrequired
Hold duration in days
interval_hoursnumber
Funding interval: 1 or 8 hours (default 8)

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.

Parameters (7)

sidestringrequired
entry_pricenumberrequired
Entry price
sizenumberrequired
Position size in base currency
funding_ratenumberrequired
Funding rate per 8h period (decimal, e.g. 0.0001)
hold_hoursnumberrequired
Hold duration in hours
fee_open_pctnumber
Open fee rate (default 0.0002)
fee_close_pctnumber
Close fee rate (default 0.0005)

system.verify

Run the full regression suite — 22 canonical test vectors 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.

No parameters.

README.md10 KBView on GitHub

TradingCalc MCP Server

Ask Claude or Cursor trade questions and get exact numbers back — not AI guesses.

"What's my PnL if I buy 0.5 BTC at $80k and sell at $95k with 5x leverage?" "Size my position: $10k account, 1% risk, long BTC at $83k, stop at $81k." "Is this carry trade worth it? 0.01% funding long, 0.05% short, $50k, 30 days."

19 deterministic tools across trade planning, risk & margin, and funding/carry. Formulas verified against 22 canonical test vectors — same inputs always produce the same outputs.

Two access surfaces: MCP (Claude Desktop / Cursor / VS Code) and REST API (/v1/primitives, /v1/workflows).

Endpoints

Surface	URL	Auth
MCP	`https://tradingcalc.io/api/mcp`	Bearer optional
REST primitives	`https://tradingcalc.io/v1/primitives/:id`	Bearer required
REST workflows	`https://tradingcalc.io/v1/workflows/:id`	Bearer required
Discovery	`https://tradingcalc.io/v1/primitives`	None
Docs	`https://tradingcalc.io/docs`	None

MCP transport: Streamable HTTP (MCP spec 2024-11-05)

Quick Start

Claude Desktop

Add to claude_desktop_config.json:

json

{
  "mcpServers": {
    "tradingcalc": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://tradingcalc.io/api/mcp"]
    }
  }
}

Cursor / VS Code

json

{
  "tradingcalc": {
    "url": "https://tradingcalc.io/api/mcp"
  }
}

Direct HTTP

bash

curl -X POST https://tradingcalc.io/api/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/call",
    "params": {
      "name": "workflow.run_liquidation_safety",
      "arguments": {
        "side": "long",
        "entryPrice": 95000,
        "leverage": 10
      }
    }
  }'

Example prompts

After connecting, just ask naturally — the AI picks the right tool automatically:

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 (19)

Tool naming follows the workflow.run_* / primitive.* / system.* namespace convention. Old flat names (pnl, liquidation, etc.) are accepted for backward compatibility.

Standard Workflows — 5 credits each (via MCP or `POST /v1/workflows/:id`)

Trade Planning

Tool	REST endpoint	Description
`workflow.run_pnl_planning`	`/v1/workflows/pnl-planning`	Net PnL, fees and gross profit/loss for a futures trade
`workflow.run_breakeven_planning`	`/v1/workflows/breakeven-planning`	Break-even price accounting for entry/exit fees
`workflow.run_exit_target`	`/v1/workflows/exit-target`	Exit price required to hit a target PnL or ROE
`workflow.run_scenario_planning`	`/v1/workflows/scenario-planning`	Multi-scenario P&L analysis across price targets
`workflow.run_dca_entry`	`/v1/workflows/dca-entry`	DCA across N price levels → avg entry, breakeven, level contribution
`workflow.run_scale_out`	`/v1/workflows/scale-out`	Partial exits at multiple levels → P&L per exit, weighted avg, overall ROI

Risk & Margin

Tool	REST endpoint	Description
`workflow.run_liquidation_safety`	`/v1/workflows/liquidation-safety`	Liquidation price for long/short isolated margin
`workflow.run_position_sizing`	`/v1/workflows/position-sizing`	Position size based on account size and max risk %
`workflow.run_max_leverage`	`/v1/workflows/max-leverage`	Maximum safe leverage based on drawdown tolerance and volatility

Funding & Carry

Tool	REST endpoint	Description
`workflow.run_funding_cost`	`/v1/workflows/funding-cost`	Cumulative funding cost over a holding period
`workflow.run_funding_arbitrage`	`/v1/workflows/funding-arbitrage`	Annualized yield from long/short basis trades across two exchanges
`workflow.run_compound_funding`	`/v1/workflows/compound-funding`	Capital growth projection from reinvesting funding income
`workflow.run_funding_breakeven`	`/v1/workflows/funding-breakeven`	Price move needed to cover funding cost + fees over holding period

Advanced Workflows — 8 credits each

Tool	REST endpoint	Description
`workflow.run_risk_reward`	`/v1/workflows/risk-reward`	Full R:R analysis: sizing + liquidation + breakeven + P&L at stop and target
`workflow.run_carry_trade`	`/v1/workflows/carry-trade`	Delta-neutral carry setup: net yield, ROI, breakeven days, verdict

Primitives — 1 credit each (via MCP or `POST /v1/primitives/:id`)

Tool	REST endpoint	Description
`primitive.average_entry`	`/v1/primitives/average_entry`	Average entry price after DCA into a position
`primitive.hedge_ratio`	`/v1/primitives/hedge_ratio`	Short perp size and funding cost to hedge a spot position

Integrated Decision Workflow — 10 credits

Tool	REST endpoint	Description
`workflow.run_pre_trade_check`	`/v1/workflows/pre-trade-check`	Full pre-trade decision: position size, liquidation, breakeven, funding cost, go/no-go signal. Accepts live exchange + symbol.

System

Tool	Description
`system.verify`	Run 22 canonical test vectors against all calculators. Returns pass/fail report.

Formulas normalized across 7 exchanges: Binance, Bybit, OKX, Hyperliquid, Aster, KuCoin, MEXC.

Rate Limits & Pricing

Plan	Req/day	Credits/mo	Price
Anonymous	20	—	Free
Free API key	200	—	Free
Trader	2,500	250	$19/mo
Builder	50,000	5,000	$79/mo
Team	250,000	25,000	$249/mo
Growth	2,000,000	150,000	$599/mo

Credits: primitive = 1 cr · standard workflow = 5 cr · advanced workflow = 8 cr · pre-trade-check = 10 cr · verification bundle = +2 cr

Get your API key → email hi@tradingcalc.io or see tradingcalc.io/pricing

Pass key as: Authorization: Bearer <your-api-key>

Self-Verification

Agents can verify all 22 canonical test vectors before trusting results:

json

{
  "jsonrpc": "2.0", "id": 1,
  "method": "tools/call",
  "params": { "name": "system.verify", "arguments": {} }
}

Response: { "status": "pass", "passed": 22, "failed": 0, "total": 22 }

Live proof: tradingcalc.io/verify

Use Cases

Trading bots — check liquidation price before every trade
AI agents — deterministic risk calculations without hallucination risk
Multi-agent systems — drop-in risk management agent in analyst + risk + execution pipelines
Dashboards — embed calculations programmatically

Why deterministic?

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).

typescript

import { RiskAgent, preTradeGate } from './examples/risk-agent-wrapper';

const agent = new RiskAgent({ apiKey: 'tc_your_key', minLiqDistancePct: 3.0 });

const result = await agent.evaluate({
  symbol: 'BTCUSDT', exchange: 'bybit',
  side: 'long', entry_price: 83000, stop_loss: 81000,
  account_balance: 10000, risk_pct: 1, leverage: 5,
  funding_rate: 0.0001, hold_hours: 24,
});

if (result.approved) {
  // execute trade — result.recommended_size, result.liquidation_price
} else {
  console.log('Rejected:', result.rejection_reason);
}

// Binary gate for execution bots
const ok = await agent.isSafe({ symbol: 'ETHUSDT', side: 'short', ... });

// Standalone function (minimal integration)
const { approved, size, liqPrice } = await preTradeGate({ ... }, 'tc_your_key');

TypeScript SDK

For code-first integrations, use tradingcalc-sdk instead of raw JSON-RPC:

bash

npm install tradingcalc-sdk

typescript

import { TradingCalcClient } from 'tradingcalc-sdk';

const tc = new TradingCalcClient({ apiKey: 'tc_your_key' });

// Workflows — orchestrated decisions
const check = await tc.workflows.preTradeCheck({ side: 'long', entry_price: 83000, leverage: 5, funding_rate: 0.0001, account_balance: 5000 });

// Primitives — single formula
const avg = await tc.primitives.averageEntry({ symbol: 'BTCUSDT', input: { fills: [{ price: 83000, quantity: 0.1 }] } });

// System
const report = await tc.system.verify();

tc.call() is available for raw MCP access. Full docs: npmjs.com/package/tradingcalc-sdk

Install

claude_desktop_config.json

{
  "mcpServers": {
    "tradingcalc": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://tradingcalc.io/api/mcp"
      ]
    }
  }
}

Desktop config is stdio-only; this bridges via mcp-remote. Native remote: Settings > Connectors.

workflow.run_pnl_planning

workflow.run_liquidation_safety

workflow.run_breakeven_planning

workflow.run_position_sizing

workflow.run_funding_cost

primitive.average_entry

workflow.run_exit_target

workflow.run_scenario_planning

workflow.run_max_leverage

primitive.hedge_ratio

workflow.run_funding_arbitrage

workflow.run_compound_funding

workflow.run_pre_trade_check

workflow.run_risk_reward

workflow.run_dca_entry

workflow.run_scale_out

workflow.run_carry_trade

workflow.run_funding_breakeven

system.verify

TradingCalc MCP Server

Endpoints

Quick Start

Claude Desktop

Cursor / VS Code

Direct HTTP

Example prompts

Tools (19)

Standard Workflows — 5 credits each (via MCP or POST /v1/workflows/:id)

Advanced Workflows — 8 credits each

Primitives — 1 credit each (via MCP or POST /v1/primitives/:id)

Integrated Decision Workflow — 10 credits

System

Rate Limits & Pricing

Self-Verification

Use Cases

Why deterministic?

Risk Agent Wrapper

TypeScript SDK

Links

Install

Standard Workflows — 5 credits each (via MCP or `POST /v1/workflows/:id`)

Primitives — 1 credit each (via MCP or `POST /v1/primitives/:id`)