API reference · v1

Trading calculations, as JSON.

Three stateless POST endpoints. Explicit units, validated inputs, and reproducible results. No account or API key.

Base URL: https://riskreward.pro. Send Content-Type: application/json. Download the OpenAPI 3.1 specification or inspect the tool catalog. MCP clients use the hosted MCP endpoint.

Input conventions

Prices, balances, P&L, and initial risk must use one quote currency. No conversion is performed. Omitted currency is labeled USD with a warning.
Percentages are percentage points: 0.05 means 0.05%, and 1 risk means 1% of the account.
All fields require JSON numbers where numeric. Unknown fields, numeric strings, non-finite values, and inverse instruments are rejected.
Direction is derived from the stop relative to entry. Target and stop must lie on opposite sides of entry.
Omitted fees explicitly mean zero. An omitted target fee uses the supplied stop fee. Funding, slippage, exchange minimum sizes, and liquidation are not modeled.
Prices and amounts are limited to an absolute magnitude of 10¹²; account risk is greater than 0 and at most 100%; fee rates are from 0 up to, but not including, 100%.

Fee-aware position size

Calculate position quantity and notional for a linear crypto futures trade from user-specified account balance, risk percentage, entry and stop. Includes separate entry/stop fees and optional target profit and net R. Direction is derived. Use when asked how much to buy or sell for a specified risk budget. Ask for missing prices or risk preference; do not invent them. Does not calculate liquidation, leverage, inverse contracts, exchange lot rounding, signals, or execute orders.

POST /api/v1/position-size

curl https://riskreward.pro/api/v1/position-size \
  -H 'Content-Type: application/json' \
  -d '{
  "accountBalance": 10000,
  "riskPercent": 1,
  "entryPrice": 100000,
  "stopPrice": 95000,
  "targetPrice": 110000,
  "quoteCurrency": "USDT",
  "fees": {
    "entryPercent": 0.02,
    "stopPercent": 0.05,
    "targetPercent": 0.02
  }
}'

Example result metrics

{
  "positionUnits": {
    "value": 0.01973359644795264,
    "unit": "base units",
    "label": "Position size"
  },
  "notional": {
    "value": 1973.3596447952639,
    "unit": "USDT",
    "label": "Entry notional"
  },
  "riskBudget": {
    "value": 100,
    "unit": "USDT",
    "label": "Initial risk budget (1R)"
  },
  "stopFees": {
    "value": 1.332017760236803,
    "unit": "USDT",
    "label": "Entry and stop fees"
  },
  "plannedLossAtStop": {
    "value": 100,
    "unit": "USDT",
    "label": "Planned loss including fees"
  },
  "grossRewardToRisk": {
    "value": 2,
    "unit": "ratio",
    "label": "Gross reward / risk"
  },
  "netRewardToRisk": {
    "value": 1.9650715342871239,
    "unit": "R",
    "label": "Net reward / initial risk"
  },
  "netProfitAtTarget": {
    "value": 196.50715342871237,
    "unit": "USDT",
    "label": "Net target profit"
  },
  "netRiskPerUnit": {
    "value": 5067.5,
    "unit": "USDT/base unit",
    "label": "Risk per unit including fees"
  },
  "breakevenWinRate": {
    "value": 33.72599913480417,
    "unit": "%",
    "label": "Breakeven win rate"
  }
}

The complete response also contains normalized inputs, calculationVersion, assumptions, warnings, formulas, documentationUrl, and reproduceUrl.

Net risk/reward after fees

Compare gross and fee-adjusted reward-to-risk, loss and profit per unit, and breakeven win rate for a linear trade with known entry, stop and target. Accepts distinct entry/stop/target fee percentages. Use for questions about a planned R ratio or how fees change it. Direction is derived from entry and stop. Does not fetch venue fees or predict execution, liquidation, or trade outcomes.

POST /api/v1/risk-reward

curl https://riskreward.pro/api/v1/risk-reward \
  -H 'Content-Type: application/json' \
  -d '{
  "entryPrice": 100,
  "stopPrice": 95,
  "targetPrice": 110,
  "quoteCurrency": "USD",
  "fees": {
    "entryPercent": 0.02,
    "stopPercent": 0.05,
    "targetPercent": 0.02
  }
}'

Example result metrics

{
  "grossRewardToRisk": {
    "value": 2,
    "unit": "ratio",
    "label": "Gross reward / risk"
  },
  "netRewardToRisk": {
    "value": 1.9650715342871239,
    "unit": "R",
    "label": "Net reward / initial risk"
  },
  "netProfitAtTarget": {
    "value": 9.958,
    "unit": "USD/base unit",
    "label": "Net target profit"
  },
  "netRiskPerUnit": {
    "value": 5.0675,
    "unit": "USD/base unit",
    "label": "Risk per unit including fees"
  },
  "breakevenWinRate": {
    "value": 33.72599913480416,
    "unit": "%",
    "label": "Breakeven win rate"
  }
}

The complete response also contains normalized inputs, calculationVersion, assumptions, warnings, formulas, documentationUrl, and reproduceUrl.

Realized trading performance

Analyze up to 500 chronological closed trades supplied by the user, each with net P&L after costs and original risk. Returns win rate, profit factor, expectancy in currency and R, total net R, and optional closed-trade equity drawdown when initial equity is supplied. Use for reviewing an existing trade sample. No account access, deposits, intratrade drawdown, forecasts, signals, or new risk recommendations.

POST /api/v1/performance

curl https://riskreward.pro/api/v1/performance \
  -H 'Content-Type: application/json' \
  -d '{
  "quoteCurrency": "USD",
  "initialEquity": 10000,
  "trades": [
    {
      "netPnl": 150,
      "initialRisk": 100
    },
    {
      "netPnl": -100,
      "initialRisk": 100
    },
    {
      "netPnl": 50,
      "initialRisk": 50
    }
  ]
}'

Example result metrics

{
  "tradeCount": {
    "value": 3,
    "unit": "trades",
    "label": "Closed trades"
  },
  "winRate": {
    "value": 66.66666666666667,
    "unit": "%",
    "label": "Win rate"
  },
  "netPnl": {
    "value": 100,
    "unit": "USD",
    "label": "Net P&L"
  },
  "expectancy": {
    "value": 33.333333333333336,
    "unit": "USD",
    "label": "Expectancy per trade"
  },
  "totalNetR": {
    "value": 1.5,
    "unit": "R",
    "label": "Total realized R"
  },
  "expectancyR": {
    "value": 0.5,
    "unit": "R",
    "label": "Expectancy per trade in R"
  },
  "profitFactor": {
    "value": 2,
    "unit": "ratio",
    "label": "Profit factor"
  },
  "breakevenTrades": {
    "value": 0,
    "unit": "trades",
    "label": "Breakeven trades"
  },
  "endingEquity": {
    "value": 10100,
    "unit": "USD",
    "label": "Ending equity"
  },
  "maxDrawdown": {
    "value": 100,
    "unit": "USD",
    "label": "Maximum closed-trade drawdown"
  },
  "maxDrawdownPercent": {
    "value": 0.9852216748768473,
    "unit": "%",
    "label": "Maximum closed-trade drawdown"
  }
}

The complete response also contains normalized inputs, calculationVersion, assumptions, warnings, formulas, documentationUrl, and reproduceUrl.

Formulas and precision

For sizing, the risk budget is account balance × risk percentage / 100. Risk per unit is absolute entry-to-stop distance plus the entry and stop fees per unit. Quantity is budget divided by that fee-inclusive risk.

Net target reward subtracts entry and target fees from the price reward. Net reward/risk divides it by the fee-inclusive initial risk, not by the price distance alone. Breakeven win rate uses those same net outcomes. A zero net target reward has a 100% threshold; negative net reward has no feasible threshold and returns null.

Performance expectancy is mean net P&L. Expectancy in R is the mean of each trade’s P&L divided by its own initial risk. Profit factor is positive net P&L divided by the magnitude of negative net P&L; it is nullwhen there is no losing P&L. Breakeven trades remain in the win-rate denominator.

Optional drawdown walks chronological closed-trade equity from the supplied starting balance. It excludes cash flows and intratrade movement. Maximum monetary and percentage drawdowns are computed independently and can refer to different peaks.

Version 1.0.0 uses JavaScript double-precision arithmetic. JSON values are not exchange-rounded; browser displays may round for readability. Apply your venue’s lot and tick constraints separately and verify risk after rounding. These outputs are scenario calculations, not executable orders.

Errors and limits

400: malformed JSON.
403: unsupported Host or Origin.
413: request exceeds 64 KiB.
415: unsupported content type.
422: missing/invalid inputs or an impossible price relationship. Inspect error.issues for field-level validation.
429: back off for the Retry-After interval. The service applies a best-effort limit of 60 requests per minute per client address and running instance; hosting protections may impose additional limits.

Performance requests accept up to 500 trades. Reproduction links are omitted when the encoded input exceeds 7,000 characters. Retain your input JSON and calculation version for larger batches. Responses are not cached.

Operational measurement

Calculation logs record the tool, transport, outcome, and duration. The service does not log the numerical inputs or result. This supports reliability and integration-usage measurement; it does not reveal why an agent chose a tool or whether a user was persuaded by a result.

Versioning

REST contracts are under /api/v1/. Results identify the formula version. Integrators should retain it with the input and check the MCP integration notes when upgrading.