{ "openapi": "3.1.1", "info": { "title": "Ledgerly Debt Payoff Planner API", "version": "1.0.0", "summary": "Avalanche vs snowball: your debt-free date, total interest and a month-by-month plan.", "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://ledgerlydebtpayoff.usefulweb.app" } ], "paths": { "/api/v1/calculate": { "post": { "operationId": "calculate", "summary": "Avalanche vs snowball: your debt-free date, total interest and a month-by-month plan.", "description": "Plans paying off several credit cards and loans: the avalanche (highest interest first), snowball (smallest balance first) or your own order with an extra monthly payment, compared with paying only the minimums. Shows the debt-free month, total interest, when each debt is gone, a month-by-month table and the minimum-payment trap of every card with a percentage minimum. Part of Ledgerly’s Debt \u0026 Growth.\n\nMethodology:\n- Each month one twelfth of the APR is added to every balance as interest (rounded to the cent, as in the Loan Amortization Calculator’s schedule).\n- The monthly amount is fixed: the first month’s minimums plus your extra payment. Every debt gets its minimum; the rest goes to the first open debt in the payoff order. When a debt is paid off, its minimum rolls over to the next one.\n- Avalanche orders by interest rate (highest first), snowball by balance (smallest first), “your order” keeps the list order; ties keep the list order.\n- Percentage minimums are the percentage of the balance (or the month’s interest plus the percentage), never below the fixed amount and at least 1 unit of the currency. “Minimum payments only” pays each debt just its own minimum, so card payments shrink as the balance falls — the minimum-payment trap.\n\nA plan, not financial advice: lenders calculate interest and minimums in different ways, and rates can change. Check your statements and talk to a free debt advice service if payments are hard to make.", "tags": [ "apps" ], "x-mcp-tool": "ledgerly_debt_payoff", "x-owner-app": "ledgerly", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LedgerlyDebtPayoffInput" }, "examples": { "example1": { "summary": "Two cards and a car loan, 150 extra per month", "value": { "currency": "EUR", "debts": [ { "name": "Credit card", "balance": 4200, "aprPercent": 22.9, "minPayment": 25, "minPercent": 2 }, { "name": "Car loan", "balance": 2800, "aprPercent": 6.9, "minPayment": 240 }, { "name": "Store card", "balance": 650, "aprPercent": 27, "minPayment": 25, "minPercent": 3 } ], "strategy": "avalanche", "extraPerMonth": 150, "startMonth": "2027-01" } }, "example2": { "summary": "Snowball with 100 extra: student loan, card, overdraft", "value": { "currency": "USD", "debts": [ { "name": "Student loan", "balance": 18000, "aprPercent": 5.5, "minPayment": 195 }, { "name": "Visa", "balance": 5200, "aprPercent": 24.99, "minPayment": 35, "minPercent": 1 }, { "name": "Overdraft", "balance": 900, "aprPercent": 19.9, "minPayment": 40 } ], "strategy": "snowball", "extraPerMonth": 100, "minimumRule": "interest-plus-percent" } }, "example3": { "summary": "One card: the minimum-payment trap", "value": { "currency": "GBP", "debts": [ { "name": "Credit card", "balance": 3000, "aprPercent": 24.9, "minPayment": 25, "minPercent": 2.5 } ], "extraPerMonth": 0 } } } } } }, "responses": { "200": { "description": "Calculation result envelope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LedgerlyDebtPayoffResult" } } } }, "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" } } } } } }, "LedgerlyDebtPayoffInput": { "type": "object", "additionalProperties": false, "properties": { "currency": { "title": "Currency", "description": "ISO code used for the labels, e.g. EUR, USD, GBP.", "type": "string", "maxLength": 3, "default": "EUR" }, "debts": { "title": "Debts", "description": "One row per credit card or loan. Cards often have a minimum of a percentage of the balance (e.g. 2 %) with a fixed floor (e.g. 25): enter both; for a fixed payment leave the percentage at 0.", "type": "array", "minItems": 1, "maxItems": 20, "items": { "type": "object", "additionalProperties": false, "properties": { "name": { "title": "Debt", "type": "string", "maxLength": 80 }, "balance": { "title": "Balance owed", "type": "number", "minimum": 0.01, "maximum": 100000000 }, "aprPercent": { "title": "APR (% per year)", "type": "number", "minimum": 0, "maximum": 100 }, "minPayment": { "title": "Minimum per month", "type": "number", "minimum": 0, "maximum": 10000000, "default": 0 }, "minPercent": { "title": "Minimum % of balance", "type": "number", "minimum": 0, "maximum": 100, "default": 0 } }, "required": [ "balance", "aprPercent" ] }, "default": [ { "name": "Credit card", "balance": 3000, "aprPercent": 21.9, "minPayment": 25, "minPercent": 2 }, { "name": "Car loan", "balance": 2400, "aprPercent": 6.5, "minPayment": 160, "minPercent": 0 } ] }, "strategy": { "title": "Payoff order", "type": "string", "enum": [ "avalanche", "snowball", "custom" ], "default": "avalanche" }, "extraPerMonth": { "title": "Extra payment per month on top of the minimums", "type": "number", "minimum": 0, "maximum": 10000000, "default": 0 }, "minimumRule": { "title": "Percentage minimums are", "description": "Only used for debts with a percentage minimum (credit cards). The fixed amount is the floor.", "type": "string", "enum": [ "percent", "interest-plus-percent" ], "default": "percent" }, "startMonth": { "title": "First payment month (YYYY-MM, optional)", "description": "Gives the debt-free date as a month; leave empty to count months only.", "type": "string", "maxLength": 7, "default": "" } }, "required": [ "debts" ] }, "LedgerlyDebtPayoffResult": { "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": [ "currency", "strategy", "totalDebt", "budgetPerMonth", "extraPerMonth", "months", "debtFreeMonth", "totalInterest", "totalPaid", "interestSavedVsMinimums", "monthsSavedVsMinimums", "strategies", "debts", "traps", "schedule" ], "properties": { "currency": { "type": "string" }, "strategy": { "type": "string", "enum": [ "avalanche", "snowball", "custom" ] }, "totalDebt": { "type": "number" }, "budgetPerMonth": { "type": "number" }, "extraPerMonth": { "type": "number" }, "months": { "type": [ "integer", "null" ] }, "debtFreeMonth": { "type": [ "string", "null" ] }, "totalInterest": { "type": [ "number", "null" ] }, "totalPaid": { "type": [ "number", "null" ] }, "interestSavedVsMinimums": { "type": [ "number", "null" ] }, "monthsSavedVsMinimums": { "type": [ "integer", "null" ] }, "strategies": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "strategy", "months", "debtFreeMonth", "totalInterest", "totalPaid", "order" ], "properties": { "strategy": { "type": "string", "enum": [ "avalanche", "snowball", "custom", "minimums" ] }, "months": { "type": [ "integer", "null" ] }, "debtFreeMonth": { "type": [ "string", "null" ] }, "totalInterest": { "type": [ "number", "null" ] }, "totalPaid": { "type": [ "number", "null" ] }, "order": { "type": "array", "items": { "type": "string" } } } } }, "debts": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "name", "balance", "aprPercent", "firstMinimum", "payoffRank", "paidOffMonth", "interest" ], "properties": { "name": { "type": "string" }, "balance": { "type": "number" }, "aprPercent": { "type": "number" }, "firstMinimum": { "type": "number" }, "payoffRank": { "type": "integer" }, "paidOffMonth": { "type": [ "integer", "null" ] }, "interest": { "type": "number" } } } }, "traps": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "name", "firstMinimum", "minimumOnlyMonths", "minimumOnlyInterest", "fixedPaymentMonths", "fixedPaymentInterest" ], "properties": { "name": { "type": "string" }, "firstMinimum": { "type": "number" }, "minimumOnlyMonths": { "type": [ "integer", "null" ] }, "minimumOnlyInterest": { "type": [ "number", "null" ] }, "fixedPaymentMonths": { "type": [ "integer", "null" ] }, "fixedPaymentInterest": { "type": [ "number", "null" ] } } } }, "schedule": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": [ "month", "label", "payment", "interest", "principal", "balance", "paidOff" ], "properties": { "month": { "type": "integer" }, "label": { "type": [ "string", "null" ] }, "payment": { "type": "number" }, "interest": { "type": "number" }, "principal": { "type": "number" }, "balance": { "type": "number" }, "paidOff": { "type": "array", "items": { "type": "string" } } } } } } }, "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" } } } } } } } }