{"openapi":"3.1.0","info":{"title":"Nivesh API","version":"0.1.0","description":"Indian personal-finance calculators: SIP/lumpsum, PPF, EPF, FD/RD, CAGR, XIRR, EMI, retirement corpus, gold/SGB — all local.\n\nEvery operation is read-only or compute-only. The same tools are available over MCP (streamable HTTP) at https://nivesh.connectorbay.com/mcp.","contact":{"name":"Unify Dynamics LLC","email":"hr@unifydynamics.com","url":"https://connectorbay.com/nivesh/docs"},"termsOfService":"https://connectorbay.com/nivesh/terms"},"servers":[{"url":"https://nivesh.connectorbay.com"}],"externalDocs":{"url":"https://connectorbay.com/nivesh/docs"},"security":[{},{"bearer":[]}],"components":{"securitySchemes":{"bearer":{"type":"http","scheme":"bearer","description":"Optional. A Pro API key raises rate limits; no credentials are required."}},"schemas":{"Error":{"type":"object","properties":{"ok":{"const":false},"error":{"type":"object"}}}}},"paths":{"/v1/tools/sip_calculator":{"post":{"operationId":"sip_calculator","summary":"SIP (systematic investment plan) growth using the standard monthly-annuity-due formula, flat or","description":"SIP (systematic investment plan) growth using the standard monthly-annuity-due formula, flat or\n    step-up. Use for \"what will a 5000 monthly SIP at 12% become in 15 years\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"monthly_investment":{"exclusiveMinimum":0,"title":"Monthly Investment","type":"number"},"annual_return_pct":{"description":"Expected annual return, %.","title":"Annual Return Pct","type":"number"},"years":{"exclusiveMinimum":0,"title":"Years","type":"number"},"step_up_pct":{"default":0.0,"description":"Annual increase to the monthly investment, %, for a step-up SIP.","minimum":0,"title":"Step Up Pct","type":"number"}},"required":["monthly_investment","annual_return_pct","years"],"title":"sip_calculatorArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/lumpsum_calculator":{"post":{"operationId":"lumpsum_calculator","summary":"One-time (lumpsum) investment growth at a given compounding frequency. Use for \"grow 5 lakh at 10% for","description":"One-time (lumpsum) investment growth at a given compounding frequency. Use for \"grow 5 lakh at 10% for\n    8 years\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"principal":{"exclusiveMinimum":0,"title":"Principal","type":"number"},"annual_return_pct":{"description":"Expected annual return, %.","title":"Annual Return Pct","type":"number"},"years":{"exclusiveMinimum":0,"title":"Years","type":"number"},"compounding":{"default":"annual","description":"annual | semi-annual | quarterly | monthly","title":"Compounding","type":"string"}},"required":["principal","annual_return_pct","years"],"title":"lumpsum_calculatorArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/ppf_calculator":{"post":{"operationId":"ppf_calculator","summary":"Public Provident Fund maturity value (annual-compounding approximation), flagging the 15-year lock-in","description":"Public Provident Fund maturity value (annual-compounding approximation), flagging the 15-year lock-in\n    and the ₹1.5 lakh annual limit. Use for \"PPF maturity value for 1.5 lakh a year for 15 years\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"yearly_investment":{"exclusiveMinimum":0,"maximum":150000,"title":"Yearly Investment","type":"number"},"years":{"minimum":1,"title":"Years","type":"integer"},"annual_rate_pct":{"default":7.1,"exclusiveMinimum":0,"title":"Annual Rate Pct","type":"number"}},"required":["yearly_investment","years"],"title":"ppf_calculatorArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/epf_calculator":{"post":{"operationId":"epf_calculator","summary":"Employees' Provident Fund maturity value from employee+employer contributions, with optional annual","description":"Employees' Provident Fund maturity value from employee+employer contributions, with optional annual\n    salary growth. Use for \"EPF corpus after 25 years on a 40,000 basic salary\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"basic_salary":{"description":"Monthly basic salary.","exclusiveMinimum":0,"title":"Basic Salary","type":"number"},"years":{"minimum":1,"title":"Years","type":"integer"},"employee_contribution_pct":{"default":12.0,"minimum":0,"title":"Employee Contribution Pct","type":"number"},"employer_contribution_pct":{"default":3.67,"minimum":0,"title":"Employer Contribution Pct","type":"number"},"annual_rate_pct":{"default":8.25,"exclusiveMinimum":0,"title":"Annual Rate Pct","type":"number"},"annual_salary_increment_pct":{"default":0.0,"minimum":0,"title":"Annual Salary Increment Pct","type":"number"}},"required":["basic_salary","years"],"title":"epf_calculatorArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/fd_rd_calculator":{"post":{"operationId":"fd_rd_calculator","summary":"Fixed-deposit or recurring-deposit maturity value. Use for \"FD maturity for 2 lakh at 7% for 3 years\"","description":"Fixed-deposit or recurring-deposit maturity value. Use for \"FD maturity for 2 lakh at 7% for 3 years\"\n    or \"RD maturity for 5000/month at 6.5% for 2 years\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"deposit_type":{"description":"fd | rd","title":"Deposit Type","type":"string"},"amount":{"description":"Principal for FD, or monthly deposit for RD.","exclusiveMinimum":0,"title":"Amount","type":"number"},"annual_rate_pct":{"minimum":0,"title":"Annual Rate Pct","type":"number"},"tenure_months":{"minimum":1,"title":"Tenure Months","type":"integer"},"compounding":{"default":"quarterly","description":"FD only: annual | semi-annual | quarterly | monthly","title":"Compounding","type":"string"}},"required":["deposit_type","amount","annual_rate_pct","tenure_months"],"title":"fd_rd_calculatorArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/cagr_calculator":{"post":{"operationId":"cagr_calculator","summary":"Compound annual growth rate between two values over a period. Use for \"CAGR from 1 lakh to 2.5 lakh in","description":"Compound annual growth rate between two values over a period. Use for \"CAGR from 1 lakh to 2.5 lakh in\n    6 years\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"initial_value":{"exclusiveMinimum":0,"title":"Initial Value","type":"number"},"final_value":{"exclusiveMinimum":0,"title":"Final Value","type":"number"},"years":{"exclusiveMinimum":0,"title":"Years","type":"number"}},"required":["initial_value","final_value","years"],"title":"cagr_calculatorArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/xirr_calculator":{"post":{"operationId":"xirr_calculator","summary":"Internal rate of return (XIRR) for cashflows on irregular dates, solved by Newton-Raphson. Use for","description":"Internal rate of return (XIRR) for cashflows on irregular dates, solved by Newton-Raphson. Use for\n    \"XIRR for these investment cashflows\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"cashflows":{"description":"List of {date: 'YYYY-MM-DD', amount: number} — negative for outflows, positive for inflows.","items":{"additionalProperties":true,"type":"object"},"title":"Cashflows","type":"array"}},"required":["cashflows"],"title":"xirr_calculatorArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/emi_calculator":{"post":{"operationId":"emi_calculator","summary":"Loan EMI, total interest, and a yearly amortization schedule. Use for \"EMI for a 40 lakh home loan at","description":"Loan EMI, total interest, and a yearly amortization schedule. Use for \"EMI for a 40 lakh home loan at\n    8.5% for 20 years\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"principal":{"exclusiveMinimum":0,"title":"Principal","type":"number"},"annual_rate_pct":{"minimum":0,"title":"Annual Rate Pct","type":"number"},"tenure_years":{"exclusiveMinimum":0,"title":"Tenure Years","type":"number"}},"required":["principal","annual_rate_pct","tenure_years"],"title":"emi_calculatorArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/retirement_corpus_calculator":{"post":{"operationId":"retirement_corpus_calculator","summary":"Required corpus at retirement (inflation-adjusted expenses over a real-return annuity) and the monthly","description":"Required corpus at retirement (inflation-adjusted expenses over a real-return annuity) and the monthly\n    SIP needed to reach it. Use for \"how much do I need to retire at 55 spending 80,000 a month today\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"current_age":{"maximum":100,"minimum":1,"title":"Current Age","type":"integer"},"retirement_age":{"maximum":100,"minimum":1,"title":"Retirement Age","type":"integer"},"monthly_expense_today":{"exclusiveMinimum":0,"title":"Monthly Expense Today","type":"number"},"inflation_pct":{"default":6.0,"minimum":0,"title":"Inflation Pct","type":"number"},"expected_return_pct":{"default":12.0,"description":"Expected annual return while accumulating, %.","title":"Expected Return Pct","type":"number"},"post_retirement_return_pct":{"anyOf":[{"type":"number"},{"type":"null"}],"default":null,"description":"Expected annual return during retirement, %; defaults to expected_return_pct.","title":"Post Retirement Return Pct"},"life_expectancy":{"default":85,"maximum":120,"minimum":1,"title":"Life Expectancy","type":"integer"}},"required":["current_age","retirement_age","monthly_expense_today"],"title":"retirement_corpus_calculatorArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}},"/v1/tools/gold_sgb_calculator":{"post":{"operationId":"gold_sgb_calculator","summary":"Physical gold or Sovereign Gold Bond returns, including SGB's simple annual interest on the initial","description":"Physical gold or Sovereign Gold Bond returns, including SGB's simple annual interest on the initial\n    value. Use for \"returns on 10 grams of SGB bought at 5000/gram now at 7200/gram after 5 years\".","tags":["tools"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"properties":{"grams":{"exclusiveMinimum":0,"title":"Grams","type":"number"},"purchase_price_per_gram":{"exclusiveMinimum":0,"title":"Purchase Price Per Gram","type":"number"},"current_price_per_gram":{"exclusiveMinimum":0,"title":"Current Price Per Gram","type":"number"},"years_held":{"exclusiveMinimum":0,"title":"Years Held","type":"number"},"is_sgb":{"default":false,"description":"True for a Sovereign Gold Bond (adds annual interest); false for physical gold.","title":"Is Sgb","type":"boolean"},"sgb_interest_pct":{"default":2.5,"minimum":0,"title":"Sgb Interest Pct","type":"number"}},"required":["grams","purchase_price_per_gram","current_price_per_gram","years_held"],"title":"gold_sgb_calculatorArguments","type":"object"}}}},"responses":{"200":{"description":"Tool result. `ok: true` on success; `ok: false` with a structured `error` (provider_unavailable, upstream_error, bad_input) when the tool could not answer.","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}},"422":{"description":"Arguments failed validation","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded (see Retry-After)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"x-read-only":true}}}}