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

Email hi@tradingcalc.io — 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": {
    "grossPnl": 500,
    "netPnl": 483.5,
    "roe": 6.04,
    "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
pro	10,000

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 https://tradingcalc.io/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-planning5 crPnL planning with fee resolution

breakeven-planning5 crBreakeven with reference fee lookup

exit-target5 crTarget exit with fee resolution

scenario-planning5 crScenario analysis, structured output

liquidation-safety5 crLiquidation with mmr from reference store

position-sizing5 crPosition sizing with fee resolution

max-leverage5 crMax leverage with reference mmr

funding-cost5 crFunding cost with optional live rate fetch

funding-arbitrage5 crFunding arb, structured yield output

compound-funding5 crCompound funding projection

pre-trade-check10 crFull pre-trade decision: sizing + liquidation + breakeven + funding. 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"
}

MCP surface

All 12 primitives + pre_trade_check + verify_calculators are available as MCP tools via Streamable HTTP.

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": "pnl",
      "arguments": { "side": "long", "entryPrice": 80000, "exitPrice": 85000, "size": 0.1 }
    }
  }'

Self-verify all formulas: { "name": "verify_calculators", "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

Email us — key within 24h. Free tier available.

hi@tradingcalc.io →