_done mortgage calculator API

openapi: 3.2.0
info:
  title: Mortgage & Loan Amortization Calculator mortgage calculator API
  description: Give this API a loan amount, an interest rate, and a repayment term, and it hands back the precise monthly payment plus a complete schedule showing — for every single month — how much goes to interest, how much reduces the balance, and what you still owe. You can also ask 'what if I pay an extra $300 a month?' or 'what if I make a $10,000 lump payment in month 24?' and it will tell you exactly how many months you save and how much interest you avoid. Every number is computed with banker's rounding and a pinned arithmetic rule so that two correct systems running the same inputs produce identical results, down to the cent. No rate lookups, no market data — you supply the rate, the API does the math.
  version: 1.0.0
  contact:
    name: _done
    url: https://forms.gle/5KzuSFH7p8hHtDmz7
    email: info@underscoredone.com
  x-openapi-url: https://mortgage-amortization.underscoredone.com/openapi.json
  x-logo:
    url: https://underscoredone.com/logo.png
    altText: _done
  x-guidance: 'POST to /calculate with principal (positive number), annual_rate_percent (0 or above), term_months (1 or above), and start_date (YYYY-MM-DD for the first payment). Optional: extra_monthly_payment (recurring extra principal each month), one_time_payments (list of objects with ''month'' and ''amount'' keys for lump-sum payments), summary_only (true to skip the row-by-row schedule array), and rounding (decimal places, default 2). The top-level scheduled_payment field is always the base principal-and-interest payment without extras. Use with_extra_payments block when extras are supplied. The schedule array reflects actual cash paid each month including extras. All dates are YYYY-MM-DD. Raises 400 for invalid inputs such as negative principal or zero term.'
  x-ai-instructions: 'POST to /calculate with principal (positive number), annual_rate_percent (0 or above), term_months (1 or above), and start_date (YYYY-MM-DD for the first payment). Optional: extra_monthly_payment (recurring extra principal each month), one_time_payments (list of objects with ''month'' and ''amount'' keys for lump-sum payments), summary_only (true to skip the row-by-row schedule array), and rounding (decimal places, default 2). The top-level scheduled_payment field is always the base principal-and-interest payment without extras. Use with_extra_payments block when extras are supplied. The schedule array reflects actual cash paid each month including extras. All dates are YYYY-MM-DD. Raises 400 for invalid inputs such as negative principal or zero term.'
  x-provider: _done — single-purpose utility APIs for developers and AI agents. Pay per call with USDC on Base Mainnet or Solana Mainnet.
  x-pricing:
    model: pay-per-call
    currency: USDC
    network: Base Mainnet or Solana Mainnet
    price: $0.01
  x-keywords:
  - math
  - mortgage
  - amortization
  - loan
  - monthly payment
  - repayment schedule
  - interest calculation
  - extra payment
  - lump sum
  - real estate
  - personal finance
  - lending
  - utility
  - api
  - ai-agent
  - pay-per-call
  - usdc
  - x402
  x-category: mortgage calculator
  x-provider-url: https://underscoredone.com
  x-agentcash-auth:
    mode: paid
  x-402:
    price: $0.01
    network: eip155:8453
    asset: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913'
    pay_to: '0xE9740820225B3918b4ddd1292C7cA4Ca0e2C2F08'
    facilitator: https://api.cdp.coinbase.com/platform/v2/x402
    scheme: exact
    description: Give this API a loan amount, an interest rate, and a repayment term, and it hands back the precise monthly payment plus a complete schedule showing — for every single month — how much goes to interest, how much reduces the balance, and what you still owe. You can also ask 'what if I pay an extra $300 a month?' or 'what if I make a $10,000 lump payment in month 24?' and it will tell you exactly how many months you save and how much interest you avoid. Every number is computed with banker's rounding and a pinned arithmetic rule so that two correct systems running the same inputs produce identical results, down to the cent. No rate lookups, no market data — you supply the rate, the API does the math.
    mime_type: application/json
    networks:
    - network: eip155:8453
      asset: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913'
      pay_to: '0xE9740820225B3918b4ddd1292C7cA4Ca0e2C2F08'
    - network: solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp
      asset: EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v
      pay_to: 8ugAWAXDB8V18kiUrGZTq1oMvU3C6Fxs8hfC6rvzQT3b
servers:
- url: https://mortgage-amortization.underscoredone.com
  description: Production
tags:
- name: mortgage calculator
paths:
  /calculate:
    post:
      tags:
      - mortgage calculator
      summary: Exact monthly payment and full amortization schedule for any fixed-rate loan
      description: Compute the exact monthly payment and full amortization schedule for any fixed-rate loan, with optional extra and lump-sum payments.
      operationId: handler_calculate_post
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/Request'
        required: true
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Response'
              examples:
                success:
                  summary: Successful response
                  value:
                    api_version: 1.0.0
                    inputs_echo:
                      principal: 400000
                      annual_rate_percent: 6.5
                      term_months: 360
                      start_date: '2026-07-01'
                    rounding:
                      mode: half_even
                      decimals: 2
                      final_payment_adjusted: true
                    scheduled_payment: 2528.27
                    summary:
                      total_paid: 910179.81
                      total_interest: 510179.81
                      final_payment: 2530.88
                      payoff_date: '2056-06-01'
                      scheduled_term_months: 360
                    with_extra_payments:
                      total_paid: 734237.48
                      total_interest: 334237.48
                      final_payment: 200.36
                      payoff_date: '2047-11-01'
                      actual_term_months: 257
                      interest_saved: 175942.33
                      months_saved: 103
                    schedule:
                    - payment_number: 1
                      date: '2026-07-01'
                      payment: 2828.27
                      scheduled_payment: 2528.27
                      extra_applied: 300.0
                      interest: 2166.67
                      principal: 661.6
                      balance: 399338.4
                    - payment_number: 2
                      date: '2026-08-01'
                      payment: 2828.27
                      scheduled_payment: 2528.27
                      extra_applied: 300.0
                      interest: 2163.08
                      principal: 665.19
                      balance: 398673.21
        '422':
          description: Unprocessable — a required field is missing or the wrong type. Check the detail field for specifics.
          content:
            application/json:
              schema:
                type: object
                properties:
                  detail:
                    type: array
        '402':
          description: Payment required. Send a signed USDC payment on Base Mainnet or Solana Mainnet using the x402 protocol.
          headers:
            X-Payment-Response:
              description: x402 payment challenge — base64-encoded JSON with payment details.
              schema:
                type: string
        '400':
          description: Bad request — your input failed validation or could not be processed. Check the detail field for specifics.
          content:
            application/json:
              schema:
                type: object
                properties:
                  detail:
                    type: string
      x-ai-instructions: 'POST to /calculate with principal (positive number), annual_rate_percent (0 or above), term_months (1 or above), and start_date (YYYY-MM-DD for the first payment). Optional: extra_monthly_payment (recurring extra principal each month), one_time_payments (list of objects with ''month'' and ''amount'' keys for lump-sum payments), summary_only (true to skip the row-by-row schedule array), and rounding (decimal places, default 2). The top-level scheduled_payment field is always the base principal-and-interest payment without extras. Use with_extra_payments block when extras are supplied. The schedule array reflects actual cash paid each month including extras. All dates are YYYY-MM-DD. Raises 400 for invalid inputs such as negative principal or zero term.'
      x-guidance: 'POST to /calculate with principal (positive number), annual_rate_percent (0 or above), term_months (1 or above), and start_date (YYYY-MM-DD for the first payment). Optional: extra_monthly_payment (recurring extra principal each month), one_time_payments (list of objects with ''month'' and ''amount'' keys for lump-sum payments), summary_only (true to skip the row-by-row schedule array), and rounding (decimal places, default 2). The top-level scheduled_payment field is always the base principal-and-interest payment without extras. Use with_extra_payments block when extras are supplied. The schedule array reflects actual cash paid each month including extras. All dates are YYYY-MM-DD. Raises 400 for invalid inputs such as negative principal or zero term.'
      x-payment-info:
        price:
          fixed:
            mode: fixed
            currency: USD
            amount: '0.01'
        protocols:
        - x402: {}
components:
  schemas:
    RoundingInfo:
      properties:
        mode:
          type: string
          title: Mode
        decimals:
          type: integer
          title: Decimals
        final_payment_adjusted:
          type: boolean
          title: Final Payment Adjusted
      type: object
      required:
      - mode
      - decimals
      - final_payment_adjusted
      title: RoundingInfo
    Response:
      properties:
        api_version:
          type: string
          title: Api Version
          description: API version
          default: 1.0.0
        inputs_echo:
          $ref: '#/components/schemas/InputsEcho'
          description: The key inputs you sent, echoed back for confirmation.
        rounding:
          $ref: '#/components/schemas/RoundingInfo'
          description: Details about how numbers were rounded.
        scheduled_payment:
          type: number
          title: Scheduled Payment
          description: The fixed monthly payment required to pay off the loan on schedule, not counting any extra payments.
        summary:
          $ref: '#/components/schemas/Summary'
          description: Overall totals for the loan without any extra payments.
        with_extra_payments:
          anyOf:
          - $ref: '#/components/schemas/WithExtraPayments'
          - type: 'null'
          description: How the loan changes if you make the extra payments you described. Only appears when extras were supplied.
        schedule:
          anyOf:
          - items:
              $ref: '#/components/schemas/ScheduleRow'
            type: array
          - type: 'null'
          title: Schedule
          description: The full month-by-month payment table. Omitted when summary_only is true.
      type: object
      required:
      - inputs_echo
      - rounding
      - scheduled_payment
      - summary
      title: Response
      example:
        api_version: 1.0.0
        inputs_echo:
          annual_rate_percent: 6.5
          principal: 400000
          start_date: '2026-07-01'
          term_months: 360
        rounding:
          decimals: 2
          final_payment_adjusted: true
          mode: half_even
        schedule: []
        scheduled_payment: 2528.27
        summary:
          final_payment: 2530.88
          payoff_date: '2056-06-01'
          scheduled_term_months: 360
          total_interest: 510179.81
          total_paid: 910179.81
    OneTimePayment:
      properties:
        month:
          type: integer
          title: Month
          description: Which payment number to apply this lump sum on, starting at 1.
        amount:
          type: number
          title: Amount
          description: The dollar amount of the one-time lump-sum principal payment. Must be greater than zero.
      type: object
      required:
      - month
      - amount
      title: OneTimePayment
      example:
        amount: 10000
        month: 24
    WithExtraPayments:
      properties:
        total_paid:
          type: number
          title: Total Paid
        total_interest:
          type: number
          title: Total Interest
        final_payment:
          type: number
          title: Final Payment
        payoff_date:
          type: string
          title: Payoff Date
        actual_term_months:
          type: integer
          title: Actual Term Months
        interest_saved:
          type: number
          title: Interest Saved
        months_saved:
          type: integer
          title: Months Saved
      type: object
      required:
      - total_paid
      - total_interest
      - final_payment
      - payoff_date
      - actual_term_months
      - interest_saved
      - months_saved
      title: WithExtraPayments
    ScheduleRow:
      properties:
        payment_number:
          type: integer
          title: Payment Number
        date:
          type: string
          title: Date
        payment:
          type: number
          title: Payment
        scheduled_payment:
          type: number
          title: Scheduled Payment
        extra_applied:
          type: number
          title: Extra Applied
        interest:
          type: number
          title: Interest
        principal:
          type: number
          title: Principal
        balance:
          type: number
          title: Balance
      type: object
      required:
      - payment_number
      - date
      - payment
      - scheduled_payment
      - extra_applied
      - interest
      - principal
      - balance
      title: ScheduleRow
    InputsEcho:
      properties:
        principal:
          type: number
          title: Principal
        annual_rate_percent:
          type: number
          title: Annual Rate Percent
        term_months:
          type: integer
          title: Term Months
        start_date:
          type: string
          title: Start Date
      type: object
      required:
      - principal
      - annual_rate_percent
      - term_months
      - start_date
      title: InputsEcho
    Summary:
      properties:
        total_paid:
          type: number
          title: Total Paid
        total_interest:
          type: number
          title: Total Interest
        final_payment:
          type: number
          title: Final Payment
        payoff_date:
          type: string
          title: Payoff Date
        scheduled_term_months:
          type: integer
          title: Scheduled Term Months
      type: object
      required:
      - total_paid
      - total_interest
      - final_payment
      - payoff_date
      - scheduled_term_months
      title: Summary
    Request:
      properties:
        principal:
          type: number
          title: Principal
          description: The total amount borrowed, in dollars. Must be greater than zero.
        annual_rate_percent:
          type: number
          title: Annual Rate Percent
          description: The yearly interest rate as a plain percentage — enter 6.5 for 6.5%. Enter 0 for an interest-free loan. Must be zero or above.
        term_months:
          type: integer
          title: Term Months
          description: How many monthly payments the loan spans. A 30-year mortgage is 360; a 5-year car loan is 60. Must be at least 1.
        start_date:
          type: string
          title: Start Date
          description: The date of the very first payment, written as YYYY-MM-DD (for example, 2026-07-01).
        extra_monthly_payment:
          type: number
          title: Extra Monthly Payment
          description: An optional extra amount you put toward principal every single month, on top of the required payment. Defaults to 0.
          default: 0.0
        one_time_payments:
          items:
            $ref: '#/components/schemas/OneTimePayment'
          type: array
          title: One Time Payments
          description: An optional list of one-time lump-sum principal payments. Each item needs a 'month' and an 'amount'.
        summary_only:
          type: boolean
          title: Summary Only
          description: Set to true if you only want the totals and scheduled payment — no row-by-row schedule.
          default: false
        rounding:
          type: integer
          maximum: 6.0
          minimum: 2.0
          title: Rounding
          description: How many decimal places to round every money value to. Default is 2 (cents). Valid range is 2 to 6.
          default: 2
      type: object
      required:
      - principal
      - annual_rate_percent
      - term_months
      - start_date
      title: Request
      example:
        annual_rate_percent: 6.5
        extra_monthly_payment: 300
        one_time_payments:
        - amount: 10000
          month: 24
        principal: 400000
        rounding: 2
        start_date: '2026-07-01'
        summary_only: false
        term_months: 360
  securitySchemes:
    siwx:
      type: apiKey
      in: header
      name: SIGN-IN-WITH-X
      description: CAIP-122 wallet signature for repeat access after payment
x-payment-accepts:
- scheme: exact
  network: eip155:8453
  payTo: '0xE9740820225B3918b4ddd1292C7cA4Ca0e2C2F08'
  asset: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913'
- scheme: exact
  network: solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp
  payTo: 8ugAWAXDB8V18kiUrGZTq1oMvU3C6Fxs8hfC6rvzQT3b
  asset: EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v