Stock Averager API

Getting started

Every operation is a POST with a JSON body. There is no authentication, no API key and no signup. Responses are application/json; errors are RFC 9457 problem details.

curl -X POST https://www.stockaverager.com/api/v1/cagr \
  -H "Content-Type: application/json" \
  -d '{"initialValue": 12000, "finalValue": 31000, "years": 7}'

When to use this API

Authentication and limits

None. The API is public and unauthenticated because every operation is a pure function over numbers you send — there is no account, no stored data and no per-caller state to protect. CORS is open, so browser-based clients can call it directly. There is no enforced rate limit today; please keep to roughly 60 requests a minute. If that has to change, it will be announced on this page before it is enforced.

Endpoints

8 operations. Each has a stable operationId, typed parameters and a response schema, so the spec can be loaded directly as LLM function-calling tool definitions.

curl -X POST https://www.stockaverager.com/api/v1/average-down \
  -H "Content-Type: application/json" \
  -d '{"shares":100,"originalPrice":80,"currentPrice":50,"targetAveragePrice":65}'

curl -X POST https://www.stockaverager.com/api/v1/cost-basis \
  -H "Content-Type: application/json" \
  -d '{"lots":[{"shares":100,"price":50,"fees":0},{"shares":100,"price":50,"fees":0}]}'

curl -X POST https://www.stockaverager.com/api/v1/sip \
  -H "Content-Type: application/json" \
  -d '{"monthlyInvestment":500,"expectedAnnualReturn":12,"years":10}'

curl -X POST https://www.stockaverager.com/api/v1/lumpsum \
  -H "Content-Type: application/json" \
  -d '{"amount":10000,"expectedAnnualReturn":9,"years":15}'

curl -X POST https://www.stockaverager.com/api/v1/swp \
  -H "Content-Type: application/json" \
  -d '{"initialInvestment":500000,"monthlyWithdrawal":3000,"expectedAnnualReturn":8}'

curl -X POST https://www.stockaverager.com/api/v1/cagr \
  -H "Content-Type: application/json" \
  -d '{"initialValue":12000,"finalValue":31000,"years":7}'

curl -X POST https://www.stockaverager.com/api/v1/break-even \
  -H "Content-Type: application/json" \
  -d '{"shares":100,"purchasePrice":50,"buyFees":10,"sellFees":10}'

curl -X POST https://www.stockaverager.com/api/v1/options/greeks \
  -H "Content-Type: application/json" \
  -d '{"spotPrice":147,"strikePrice":150,"daysToExpiry":30,"volatilityPercent":28,"riskFreeRatePercent":4,"optionType":"call"}'

Errors

Errors follow RFC 9457 problem details and are served as application/problem+json. Beyond the standard fields, every response carries a stable code to branch on and a hint describing the fix; validation failures add a per-field errors array.

{
  "type": "https://www.stockaverager.com/docs#errors-validation-failed",
  "title": "Request failed validation",
  "status": 422,
  "detail": "1 field could not be accepted. See \"errors\" for each one.",
  "code": "validation_failed",
  "hint": "Fix the listed fields and retry.",
  "errors": [
    {
      "field": "years",
      "code": "range",
      "message": "\"years\" must be greater than 0 and at most 50, received 0.",
      "hint": "Adjust \"years\" so it is greater than 0 and at most 50."
    }
  ]
}

For AI agents

The spec at /openapi.json is OpenAPI 3.1 with a unique operationId, a description and typed schemas on every operation, which is what function-calling formats need. Site-wide guidance lives in /llms.txt and /agent-instructions.md. Every page on this site also serves Markdown from the same URL — send Accept: text/markdown or append .md to any path.