tradingcalc-sdk

TypeScript SDK for TradingCalc — deterministic crypto futures risk & funding calculations.

Not AI. Not estimates. Same inputs, same output, every time.

Install

npm install tradingcalc-sdk

Quick start

import { TradingCalcClient } from 'tradingcalc-sdk';

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

// Net PnL for a BTC long
const result = await tc.workflows.pnl({
  side: 'long',
  entryPrice: 83000,
  exitPrice: 85000,
  size: 0.1,
});
// { pnl: 194.09, pnlPct: 0.0234, fees: 5.91, gross: 200 }

// Full pre-trade risk check
const check = await tc.workflows.preTradeCheck({
  side: 'long',
  entry_price: 83000,
  stop_loss: 81000,
  account_balance: 5000,
  risk_pct: 2,
  leverage: 5,
  funding_rate: 0.0001,
  hold_hours: 24,
});
// { safety: 'ok', liquidation_price: 66895, summary_b: 'Liquidation 19.4% away', ... }

Namespaces

The client exposes three namespaces that mirror the tool taxonomy:

tc.workflows.*   // orchestrated decisions — multi-step, returns verdict + numbers
tc.primitives.*  // raw computation — single formula, no opinion
tc.system.*      // diagnostics

tc.workflows

| Method | Tool | Description | |---|---|---| | tc.workflows.pnl() | workflow.run_pnl_planning | Net PnL, ROE, fees, gross | | tc.workflows.breakeven() | workflow.run_breakeven_planning | Break-even price with fees | | tc.workflows.targetExit() | workflow.run_exit_target | Exit price for target PnL/ROE | | tc.workflows.positionSize() | workflow.run_position_sizing | Position size from risk % | | tc.workflows.scenario() | workflow.run_scenario_planning | Multi-target P&L table | | tc.workflows.liquidation() | workflow.run_liquidation_safety | Liquidation price | | tc.workflows.maxLeverage() | workflow.run_max_leverage | Max safe leverage | | tc.workflows.fundingCost() | workflow.run_funding_cost | Funding cost over N days | | tc.workflows.fundingArb() | workflow.run_funding_arbitrage | Cross-exchange funding yield | | tc.workflows.compoundFunding() | workflow.run_compound_funding | Compound funding with decay | | tc.workflows.preTradeCheck() | workflow.run_pre_trade_check | Full pre-trade risk analysis |

tc.primitives

| Method | Tool | Description | |---|---|---| | tc.primitives.averageEntry() | primitive.average_entry | Average entry after DCA | | tc.primitives.hedgeRatio() | primitive.hedge_ratio | Spot-to-perp hedge size |

tc.system

| Method | Tool | Description | |---|---|---| | tc.system.verify() | system.verify | Run 22 canonical test vectors |

Authentication

// Anonymous — 20 calls/day, no signup
const tc = new TradingCalcClient();

// API key — 250+ calls/month, get at tradingcalc.io/pricing
const tc = new TradingCalcClient({ apiKey: 'tc_your_key' });

Error handling

import { TradingCalcClient, TradingCalcError } from 'tradingcalc-sdk';

try {
  const result = await tc.workflows.liquidation({ side: 'long', entryPrice: 83000, leverage: 10 });
} catch (e) {
  if (e instanceof TradingCalcError) {
    console.error(e.code, e.message); // JSON-RPC error code + message
  }
}

Raw MCP call

For tools not yet covered by typed helpers:

const result = await tc.call('workflow.run_pre_trade_check', {
  side: 'long',
  entry_price: 83000,
  // ...
});

Verification

Every formula is regression-tested against 22 canonical vectors:

const report = await tc.system.verify();
// { status: 'pass', passed: 22, failed: 0, total: 22, timestamp: '...' }

Live proof: tradingcalc.io/verify

Migrating from v1

// v1
await tc.pnl({ ... })
await tc.averageEntry({ ... })
await tc.verify()

// v2
await tc.workflows.pnl({ ... })
await tc.primitives.averageEntry({ ... })
await tc.system.verify()

tc.call() is unchanged.

Links

• API docs
• For developers
• Pricing
• Changelog