REST · MCP · Streamable HTTP

API Reference

Deterministic compute for futures trading. Two surfaces: REST /v1/ for direct integration, MCP for AI agents.

Quick start

1. Get an API key

Request access at tradingcalc.io/request-access — key delivered within 24h. Or use the anonymous sandbox (20 calls/day, no key required).

2. Call a primitive

curl -X POST https://tradingcalc.io/v1/primitives/pnl \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "side": "long",
    "entryPrice": 80000,
    "exitPrice": 85000,
    "size": 0.1
  }'

3. Check the result

{
  "request_id": "uuid",
  "execution_id": "uuid",
  "primitive_id": "pnl",
  "primitive_version": "v1.0",
  "status": "completed",
  "result": {
    "gross":  500,
    "pnl":    483.5,
    "pnlPct": 0.0604,
    "fees":   16.5
  },
  "trust": {
    "verification_status": "verified",
    "verification_level": 1,
    "manifest_id": "..."
  }
}

Auth & rate limits

All /v1/* endpoints require a Bearer token. Anonymous requests return 401.

Authorization: Bearer tc_<key>

Plan	Requests / day
free	200
trader	2,500
builder	50,000
team	250,000
growth	unlimited

Every response includes X-RateLimit-Remaining. Exceeded limit → 429 rate_limit_exceeded.

Primitives

Single-calculator calls. 1 credit each. All inputs are user-provided — no live data fetch.

List all primitives (no auth)

GET https://tradingcalc.io/v1/primitives

Run a primitive

POST /v1/primitives/:primitive_id

pnlNet PnL, ROE, fees for a futures trade

liquidationLiquidation price, isolated margin

breakevenBreak-even exit price after fees

risk_sizerPosition size from max-risk USDT + stop-loss

funding_costTotal funding cost over a holding period

average_entryWeighted average entry from multiple fills

target_exitExit price to hit a target PnL or ROE

scenarioPnL table across price-change percentages

max_leverageMax safe leverage from drawdown + volatility

compound_fundingCapital growth from reinvesting funding income

funding_arbFunding arbitrage yield across two exchanges

hedge_ratioPerp short size to hedge a spot position

Full input schemas: GET /v1/primitives → input_schema per primitive.

Workflows

Orchestrated operations — resolve live market data, apply reference fee schedules, return structured decision output.

POST https://tradingcalc.io/v1/workflows/:workflow_id

pnl-planningworkflow.run_pnl_planning

5 crPnL planning with fee resolution

breakeven-planningworkflow.run_breakeven_planning

5 crBreakeven with reference fee lookup

exit-targetworkflow.run_exit_target

5 crTarget exit with fee resolution

scenario-planningworkflow.run_scenario_planning

5 crScenario analysis, structured output

dca-entryworkflow.run_dca_entry

5 crDCA across N price levels → avg entry, breakeven, level contribution

scale-outworkflow.run_scale_out

5 crPartial exits at multiple levels → P&L and ROI per exit, weighted avg

liquidation-safetyworkflow.run_liquidation_safety

5 crLiquidation with mmr from reference store

position-sizingworkflow.run_position_sizing

5 crPosition sizing with fee resolution

max-leverageworkflow.run_max_leverage

5 crMax leverage with reference mmr

risk-rewardworkflow.run_risk_reward

8 crFull R:R analysis: sizing + liquidation + breakeven + P&L at stop and target

funding-costworkflow.run_funding_cost

5 crFunding cost with optional live rate fetch

funding-arbitrageworkflow.run_funding_arbitrage

5 crFunding arb, structured yield output

compound-fundingworkflow.run_compound_funding

5 crCompound funding projection

funding-breakevenworkflow.run_funding_breakeven

5 crPrice move needed to cover funding cost + fees over holding period

carry-tradeworkflow.run_carry_trade

8 crDelta-neutral carry setup: net yield, ROI, breakeven days, profitability classification

pre-trade-checkworkflow.run_pre_trade_check

10 crFull pre-trade analysis: sizing + liquidation + breakeven + funding + safety classification. Accepts live exchange data.

Example — pre-trade-check with live funding rate

curl -X POST https://tradingcalc.io/v1/workflows/pre-trade-check \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "side": "long",
    "entry_price": 80000,
    "stop_loss": 78000,
    "account_balance": 10000,
    "risk_pct": 1,
    "leverage": 10,
    "exchange": "binance",
    "symbol": "BTCUSDT"
  }'

Response contract

Primitive response

{
  "request_id":        "uuid",
  "execution_id":      "uuid",
  "primitive_id":      "pnl",
  "primitive_version": "v1.0",
  "status":            "completed",
  "result":            { ... },
  "metadata": {
    "degraded_mode":   false,
    "request_surface": "api",
    "completed_at":    "2026-04-06T00:00:00.000Z"
  },
  "trust": {
    "verification_status": "verified",
    "verification_level":  1,
    "manifest_id":         "cuid or null"
  }
}

Workflow response

{
  "request_id":       "uuid",
  "execution_id":     "uuid",
  "workflow_id":      "pre-trade-check",
  "workflow_version": "v1.0",
  "status":           "completed",
  "result":           { ... },
  "metadata": {
    "executed_class":  "integrated_decision",
    "degraded_mode":   false,
    "request_surface": "api",
    "completed_at":    "2026-04-06T00:00:00.000Z"
  },
  "trust": {
    "verification_status": "verified",
    "verification_level":  1,
    "manifest_id":         "cuid or null"
  }
}

trust.verification_status — verified (all inputs deterministic) or degraded (live market data used but not validated).

trust.manifest_id — non-null when API key has a workspace. Identifies the immutable execution record.

metadata.degraded_mode — true only for workflows that fetched live market data.

Error codes

HTTP	error	when
401	unauthorized	Missing or invalid API key
400	invalid_input	Validation failed — message contains field details
404	primitive_not_found	Unknown primitive_id
404	workflow_not_found	Unknown workflow slug
429	rate_limit_exceeded	Daily quota exhausted — check X-RateLimit-Remaining
502	upstream_error	Live funding rate fetch failed (pre-trade-check only)

{
  "error":   "invalid_input",
  "message": "entryPrice: Required; side: Invalid enum value"
}

TypeScript SDK

Official SDK — namespaced API, full TypeScript types, zero dependencies. Wraps both /v1/primitives/* and /v1/workflows/* REST endpoints.

Install

npm install tradingcalc-sdk

client.primitives.* — raw single-calculator calls (1 credit)

import { TradingCalcClient } from 'tradingcalc-sdk';

const client = new TradingCalcClient({ apiKey: 'tc_...' });

// All 12 primitives available
const pnl = await client.primitives.pnl({
  side: 'long', entryPrice: 80000, exitPrice: 85000, size: 0.1
});
// → { pnl: 483.5, pnlPct: 0.0604, fees: 16.5, gross: 500 }

const liq = await client.primitives.liquidation({
  side: 'long', entryPrice: 80000, leverage: 10
});
// → { liqPrice: 72360 }

const sizing = await client.primitives.positionSizer({
  side: 'long', entryPrice: 80000, stopLoss: 78000, riskUsdt: 100
});
// → { sizeBase: 0.05, sizeQuote: 4000, margin: 400, stopDistPct: 2.5 }

client.workflows.* — orchestrated decision output (5–10 credits)

// Risk/Reward analysis — sizing + liquidation + breakeven + P&L at stop/target
const rr = await client.workflows.riskReward({
  side: 'long',
  entry_price: 80000, stop_loss: 78000, take_profit: 86000,
  account_balance: 10000, risk_pct: 1, leverage: 10
});
// → { risk_reward_ratio: 3, verdict: 'strong', pnl_at_stop: -100, pnl_at_target: 300, ... }

// DCA entry — avg price, breakeven, per-level contribution
const dca = await client.workflows.dcaEntry({
  side: 'long',
  entries: [{ price: 80000, size: 0.1 }, { price: 78000, size: 0.15 }]
});
// → { avg_entry_price: 78800, breakeven_price: 78897, levels: [...] }

// Full pre-trade check with live funding rate
const check = await client.workflows.preTradeCheck({
  side: 'long', entry_price: 80000, stop_loss: 78000,
  account_balance: 10000, risk_pct: 1, leverage: 10,
  funding_rate: 0.0001, hold_hours: 24
});
// → { verdict: 'safe', liquidation_price: ..., breakeven_price: ..., ... }

All methods at a glance

client.primitives.*pnl · liquidation · breakeven · positionSizer · targetExit · averageEntry · scenario · fundingCost · fundingArb · compoundFunding · maxLeverage · hedgeRatio

client.workflows.*pnl · breakeven · targetExit · positionSize · scenario · dcaEntry · scaleOut · liquidation · maxLeverage · riskReward · fundingCost · fundingArb · compoundFunding · fundingBreakeven · carryTrade · preTradeCheck

client.system.*verify()

Source: github.com/SKalinin909/tradingcalc-mcp · npm: tradingcalc-sdk

MCP surface

19 MCP tools via Streamable HTTP: 12 calculator tools (namespaced as workflow.run_* or primitive.*) + 6 standalone workflows + system.verify. MCP tool names are shown in the workflow table above.

Claude Desktop

// ~/.claude/claude_desktop_config.json
{
  "mcpServers": {
    "tradingcalc": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://tradingcalc.io/api/mcp",
               "--header", "Authorization: Bearer YOUR_API_KEY"]
    }
  }
}

Cursor / VS Code

{
  "tradingcalc": {
    "url": "https://tradingcalc.io/api/mcp",
    "headers": { "Authorization": "Bearer YOUR_API_KEY" }
  }
}

Direct JSON-RPC

curl -X POST https://tradingcalc.io/api/mcp \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -d '{
    "jsonrpc": "2.0", "id": 1,
    "method": "tools/call",
    "params": {
      "name": "workflow.run_pnl_planning",
      "arguments": { "side": "long", "entryPrice": 80000, "exitPrice": 85000, "size": 0.1 }
    }
  }'

Self-verify all formulas: { "name": "system.verify", "arguments": {} } → 22 canonical vectors, pass/fail. Live proof →

Pricing

Credits table, plans, overage rates, commercial use.

View pricing →

Verification

Live proof — 22 canonical vectors, per-formula results.

View proof →

Get a key

Request access — key within 24h. Free tier available.

Request access →

Concepts

What deterministic computation means and how workflows are built.

Computation layer →Workflows →