{
  "openapi": "3.1.1",
  "info": {
    "title": "RavingDesk Position Size & Risk Planner API",
    "version": "1.0.0",
    "summary": "Size a long or short paper trade from your risk budget, stop, target and round-trip fee.",
    "description": "Every endpoint performs the same calculation as the human page and returns inputs, result, units, assumptions, sources, warnings and computedAt. MCP endpoint: /mcp."
  },
  "servers": [
    {
      "url": "https://ravingdeskpositionsize.usefulweb.app"
    }
  ],
  "paths": {
    "/api/v1/calculate": {
      "post": {
        "operationId": "calculate",
        "summary": "Size a long or short paper trade from your risk budget, stop, target and round-trip fee.",
        "description": "Calculates how many units fit a fixed risk budget (account × risk %) between entry and stop, including an estimated round-trip fee, plus the loss at the stop, the profit at the target, reward/risk and a price-move map. It is the risk planner of the RavingDesk paper-trading workspace; it does not place orders.\n\nMethodology:\n- Risk budget = account × risk % ÷ 100. The estimated round-trip fee is subtracted first, so quantity = (risk budget − fee) ÷ |entry − stop|.\n- Loss at the stop = quantity × |entry − stop| + fee (equals the risk budget); profit at the target = quantity × |target − entry| − fee; reward/risk = profit ÷ loss.\n- For a long the stop must be below and the target above the entry; for a short it is the other way round.\n- The move map shows the gross profit or loss of the planned quantity at −10 %, −5 %, 0, +5 % and +10 % from the entry, without fees.\n- Quantities are fractional; round down to whole units or lot sizes yourself. Stops are not guaranteed fills: gaps and slippage can make the real loss larger.\n\nPaper-trading calculation for education and planning only. It is not investment, tax or legal advice, uses only the numbers you enter and never places an order.",
        "tags": [
          "apps"
        ],
        "x-mcp-tool": "ravingdesk_position_size",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/RavingdeskPositionSizeInput"
              },
              "examples": {
                "example1": {
                  "summary": "Long: 10,000 account, 1 % risk, entry 100, stop 95, target 110, fee 4",
                  "value": {
                    "side": "long",
                    "account": 10000,
                    "riskPercent": 1,
                    "entry": 100,
                    "stop": 95,
                    "target": 110,
                    "fee": 4
                  }
                },
                "example2": {
                  "summary": "Short: 25,000 account, 0.5 % risk, entry 50, stop 52.5, target 45",
                  "value": {
                    "side": "short",
                    "account": 25000,
                    "riskPercent": 0.5,
                    "entry": 50,
                    "stop": 52.5,
                    "target": 45,
                    "fee": 2
                  }
                },
                "example3": {
                  "summary": "Tight stop: 5,000 account, 2 % risk, entry 20, stop 19.8, target 21",
                  "value": {
                    "side": "long",
                    "account": 5000,
                    "riskPercent": 2,
                    "entry": 20,
                    "stop": 19.8,
                    "target": 21,
                    "fee": 1
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Calculation result envelope.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/RavingdeskPositionSizeResult"
                }
              }
            }
          },
          "400": {
            "description": "Malformed JSON body.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "422": {
            "description": "Invalid input (see errors[]).",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          },
          "429": {
            "description": "Rate limit exceeded (see Retry-After).",
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/Problem"
                }
              }
            }
          }
        }
      }
    },
    "/api/v1/tool": {
      "get": {
        "operationId": "getToolDefinition",
        "summary": "Inputs, output schema and examples for this tool",
        "responses": {
          "200": {
            "description": "Tool definition.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "Problem": {
        "type": "object",
        "description": "RFC 9457 problem details. 422 responses include per-field `errors`.",
        "required": [
          "type",
          "title",
          "status",
          "detail"
        ],
        "properties": {
          "type": {
            "type": "string"
          },
          "title": {
            "type": "string"
          },
          "status": {
            "type": "integer"
          },
          "detail": {
            "type": "string"
          },
          "code": {
            "type": "string"
          },
          "errors": {
            "type": "array",
            "items": {
              "type": "object",
              "required": [
                "field",
                "message"
              ],
              "properties": {
                "field": {
                  "type": "string"
                },
                "message": {
                  "type": "string"
                }
              }
            }
          }
        }
      },
      "RavingdeskPositionSizeInput": {
        "type": "object",
        "additionalProperties": false,
        "properties": {
          "side": {
            "title": "Direction",
            "type": "string",
            "enum": [
              "long",
              "short"
            ],
            "default": "long"
          },
          "account": {
            "title": "Account size",
            "description": "Paper account value in your account currency.",
            "type": "number",
            "minimum": 0.01,
            "maximum": 1000000000,
            "default": 10000
          },
          "riskPercent": {
            "title": "Risk per trade",
            "type": "number",
            "minimum": 0.0001,
            "maximum": 100,
            "default": 1,
            "x-unit": "%"
          },
          "entry": {
            "title": "Entry price",
            "type": "number",
            "minimum": 1e-8,
            "maximum": 1000000000,
            "default": 100
          },
          "stop": {
            "title": "Stop price",
            "description": "Below entry for a long, above entry for a short.",
            "type": "number",
            "minimum": 1e-8,
            "maximum": 1000000000,
            "default": 95
          },
          "target": {
            "title": "Target price",
            "description": "Above entry for a long, below entry for a short.",
            "type": "number",
            "minimum": 1e-8,
            "maximum": 1000000000,
            "default": 110
          },
          "fee": {
            "title": "Estimated round-trip fee",
            "description": "Entry plus exit fee in account currency; it is taken out of the risk budget.",
            "type": "number",
            "minimum": 0,
            "maximum": 1000000000,
            "default": 0
          }
        },
        "required": [
          "account",
          "riskPercent",
          "entry",
          "stop",
          "target"
        ]
      },
      "RavingdeskPositionSizeResult": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "schemaVersion",
          "tool",
          "computedAt",
          "inputs",
          "summary",
          "result",
          "units",
          "assumptions",
          "sources",
          "warnings",
          "presentation",
          "links"
        ],
        "properties": {
          "schemaVersion": {
            "type": "string",
            "const": "1.0"
          },
          "tool": {
            "type": "object",
            "additionalProperties": false,
            "required": [
              "id",
              "name",
              "version"
            ],
            "properties": {
              "id": {
                "type": "string"
              },
              "name": {
                "type": "string"
              },
              "version": {
                "type": "string"
              }
            }
          },
          "computedAt": {
            "type": "string",
            "format": "date-time"
          },
          "inputs": {
            "type": "object",
            "description": "Normalised inputs actually used, including applied defaults."
          },
          "summary": {
            "type": "string"
          },
          "result": {
            "type": "object",
            "additionalProperties": false,
            "required": [
              "side",
              "quantity",
              "riskBudget",
              "riskPerUnit",
              "potentialLoss",
              "potentialProfit",
              "rewardRisk",
              "notional",
              "notionalPercentOfAccount",
              "scenarios"
            ],
            "properties": {
              "side": {
                "type": "string",
                "enum": [
                  "long",
                  "short"
                ]
              },
              "quantity": {
                "type": "number",
                "description": "Fractional units that fit the risk budget after the fee."
              },
              "riskBudget": {
                "type": "number"
              },
              "riskPerUnit": {
                "type": "number"
              },
              "potentialLoss": {
                "type": "number",
                "description": "Loss if filled exactly at the stop, fee included."
              },
              "potentialProfit": {
                "type": "number",
                "description": "Profit if filled exactly at the target, fee included."
              },
              "rewardRisk": {
                "type": "number"
              },
              "notional": {
                "type": "number"
              },
              "notionalPercentOfAccount": {
                "type": "number"
              },
              "scenarios": {
                "type": "array",
                "items": {
                  "type": "object",
                  "additionalProperties": false,
                  "required": [
                    "move",
                    "price",
                    "grossPnl"
                  ],
                  "properties": {
                    "move": {
                      "type": "number"
                    },
                    "price": {
                      "type": "number"
                    },
                    "grossPnl": {
                      "type": "number"
                    }
                  }
                }
              }
            }
          },
          "units": {
            "type": "object",
            "additionalProperties": {
              "type": "string"
            }
          },
          "assumptions": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "sources": {
            "type": "array",
            "items": {
              "type": "object",
              "additionalProperties": false,
              "required": [
                "title"
              ],
              "properties": {
                "title": {
                  "type": "string"
                },
                "url": {
                  "type": "string"
                },
                "publisher": {
                  "type": "string"
                },
                "retrievedAt": {
                  "type": "string"
                },
                "note": {
                  "type": "string"
                }
              }
            }
          },
          "warnings": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "presentation": {
            "type": "array",
            "items": {
              "type": "object"
            },
            "description": "Display blocks used by the human page (same data)."
          },
          "links": {
            "type": "object",
            "additionalProperties": false,
            "required": [
              "human",
              "api",
              "openapi",
              "methodology"
            ],
            "properties": {
              "human": {
                "type": "string",
                "format": "uri"
              },
              "api": {
                "type": "string",
                "format": "uri"
              },
              "openapi": {
                "type": "string",
                "format": "uri"
              },
              "methodology": {
                "type": "string",
                "format": "uri"
              }
            }
          }
        }
      }
    }
  }
}