> ## Documentation Index
> Fetch the complete documentation index at: https://docs.pylon.mortgage/llms.txt
> Use this file to discover all available pages before exploring further.

# Overview

> Learn how Pylon's programmatic structuring optimizes over thousands of loan structure permutations to find the most optimal structure for borrowers, saving money on out-of-pocket costs and interest over the life of the loan.

Pylon's pricing engine fundamentally differs from traditional Products & Pricing Engines (PPE) and Loan Origination Systems (LOS). While traditional systems handle one loan structure at a time, Pylon's programmatic structuring evaluates thousands of loan structure permutations simultaneously to find the optimal solution for each borrower.

## The traditional approach

In traditional PPE and LOS systems, the workflow typically looks like this:

<Steps>
  <Step title="Create a structure">
    Manually create a loan structure (e.g., 3% down, 20% down to avoid PMI).
  </Step>

  <Step title="Price the loan">
    Submit the structure to the pricing engine to get rates and costs.
  </Step>

  <Step title="Check guidelines">
    Put the pricing back into the loan file and check if [DTI](/entity-models/key-concepts/dti) rules are met.
  </Step>

  <Step title="Restructure if needed">
    If guidelines are breached, manually restructure the loan and repeat the
    process.
  </Step>
</Steps>

This iterative process is time-consuming, error-prone, and often results in suboptimal loan structures based on "tribal knowledge" rather than data-driven optimization.

## Pylon's programmatic approach

Pylon's pricing engine uses **programmatic structuring** that:

<CardGroup cols={2}>
  <Card title="Evaluates thousands of structures" icon="grid">
    Simultaneously tests thousands of loan structure permutations to find
    optimal solutions.
  </Card>

  <Card title="Encodes all guidelines" icon="code">
    All guidelines and rates are encoded in the software, ensuring comprehensive
    evaluation.
  </Card>

  <Card title="Optimizes automatically" icon="sparkles">
    Finds the most optimal structure based on your objective (minimize
    out-of-pocket, monthly payment, etc.).
  </Card>

  <Card title="Avoids manual iteration" icon="check-circle">
    No need to manually restructure and re-price. The system finds the best
    option automatically.
  </Card>
</CardGroup>

## Why traditional structures are suboptimal

The mortgage industry has developed "tribal knowledge" around traditional down payment structures:

* **3% down**: Common minimum for conventional loans
* **20% down**: Traditional amount to avoid PMI (Private Mortgage Insurance)

However, these traditional structures often ignore critical factors:

* **Pricing implications**: Different [LTV](/entity-models/key-concepts/ltv) ratios have different pricing impacts
* **[LLPA](/entity-models/key-concepts/llpa) cliffs**: [Loan-Level Price Adjustments (LLPAs)](/entity-models/key-concepts/llpa) can create significant cost jumps at certain thresholds
* **Guideline eligibility**: Some structures may not be optimal even if they meet minimum guidelines

***

## Scenario 1 - [LLPA](/entity-models/key-concepts/llpa) cliff causes pricing ineligibility due to cash-to-close constraints

### Initial structure

* **Purchase price**: \$1,250,000
* **Down payment**: \$250,000 (20%)
* **Loan amount**: \$1,000,000
* **[LTV](/entity-models/key-concepts/ltv)**: 80.00%
* **Credit score**: 705
* **Occupancy**: Primary residence
* **Program**: Conventional fixed-rate

### Borrower cash-to-close constraints

The borrower has explicit liquidity limits:

* **Maximum total cash to close**: \$265,000
* **Planned down payment**: \$250,000
* **Available funds for fees, points, and [reserves](/entity-models/key-concepts/reserves)**: \$15,000
  The borrower cannot increase total cash to close beyond this amount without liquidating assets or delaying the transaction.

### Pricing impact

At **exactly 80.00% [LTV](/entity-models/key-concepts/ltv)**, the loan triggers multiple [LLPAs](/entity-models/key-concepts/llpa):

| [LLPA](/entity-models/key-concepts/llpa) source    | Adjustment |
| -------------------------------------------------- | ---------- |
| [LTV](/entity-models/key-concepts/ltv) (80%)       | 0.75%      |
| Credit score ≤ 720                                 | 0.375%     |
| Loan size                                          | 0.25%      |
| **Total [LLPA](/entity-models/key-concepts/llpa)** | **1.375%** |

**Total [LLPA](/entity-models/key-concepts/llpa) cost**: \$13,750

### Why this structure fails

To execute this loan at par pricing, the borrower would need to pay:

* **[LLPAs](/entity-models/key-concepts/llpa)**: \$13,750
* **Base closing costs (excluding down payment)**: \~\$14,000
* **[LLPA](/entity-models/key-concepts/llpa) charges**: \$13,750
* **Total non-down-payment cash required**: \~\$27,750

<Warning>
  The loan meets guideline requirements but is not executable due to
  cash-to-close constraints. This exceeds the borrower's available \$15,000 by
  \$12,750, rendering the structure non-executable.
</Warning>

## Using optimized pricing

### The magic behind optimized structures

Our optimizer deterministically evaluates mortgage structures given a defined set of constraints and objectives.

It treats all borrower dollars as **fungible across uses**, including down payment, points, closing costs, prepaid items, [reserves](/entity-models/key-concepts/reserves), and pricing adjustments, and reallocates them to identify the optimal executable structure.

Given:

* Hard constraints (program rules, guideline requirements, cash-to-close limits)
* A borrower-defined **out-of-pocket maximum**
* Optimization objectives (for example, minimizing [PITIA](/entity-models/key-concepts/piti) or cash to close)

The optimizer produces a loan structure that:

<Steps>
  <Step title="Satisfy all constraints">
    Enforce cash limits, reserve requirements, eligibility rules, and pricing
    bounds as hard constraints.
  </Step>

  <Step title="Optimize for borrower objectives">
    Choose a goal (e.g. minimize out-of-pocket, minimize monthly [PITIA](/entity-models/key-concepts/piti), or minimize down payment). The optimizer selects the best structure for that objective within the feasible space.
  </Step>

  <Step title="Guarantee guideline compliance">
    Produce a structure that definitively passes guidelines with no manual
    overrides, exceptions, or guesswork.
  </Step>
</Steps>

### Borrower preferences and pricing constraints

The optimizer only considers structures that stay within **hard constraints**. Those constraints come from **borrower preferences** (stored on the loan) or from **pricing constraints** you pass when calling pricing (e.g. when calculating the most optimal structure). If you don't pass pricing constraints, the system uses the loan's borrower preferences.

Common constraints include:

| Constraint              | Purpose                                                                                                                                                                                                                                                                       |
| ----------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **`maxOutOfPocket`**    | Total cash the borrower can bring to closing (down payment + fees, points, prepaids). The optimizer will not suggest structures that exceed this.                                                                                                                             |
| **`maxLtv`**            | Maximum [LTV](/entity-models/key-concepts/ltv). Keeps the loan within the borrower's or program's comfort zone (e.g. cap at 90% LTV). With `MIN_DOWN_PAYMENT`, yields [fixed structures](/guides/getting-started/pricing-optimizations/fixed-loan-structures) (e.g. 90% LTV). |
| **`closingCosts`**      | Cap on closing costs (excluding down payment).                                                                                                                                                                                                                                |
| **`monthlyPayment`**    | Cap on [PITIA](/entity-models/key-concepts/piti). Ensures the payment stays within the borrower's budget.                                                                                                                                                                     |
| **`maxDiscountPoints`** | Limits how many points the borrower is willing to buy.                                                                                                                                                                                                                        |
| **`downPaymentAmount`** | Fixed down payment when the borrower has already decided the amount.                                                                                                                                                                                                          |

Borrower preferences are set per loan (e.g. via the loan's borrower preferences). When you run pricing or optimal-structure calculations, you can optionally pass **pricing constraints** to override or narrow those bounds for that specific run. The optimizer then finds the best structure that satisfies both program/guideline rules and these constraints.

### Optimization objectives

Choose the objective that aligns with your borrower's goals:

| Objective           | Use Case                            | Description                                                                                                                                                                                                                                                                                          |
| ------------------- | ----------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `MIN_OUT_OF_POCKET` | Borrower has limited cash           | Minimizes total cash required at closing                                                                                                                                                                                                                                                             |
| `MIN_PITIA`         | Borrower focused on monthly payment | Minimizes monthly [PITIA](/entity-models/key-concepts/piti) (principal, interest, taxes, insurance, and association fees)                                                                                                                                                                            |
| `MIN_DOWN_PAYMENT`  | Borrower wants to preserve cash     | Middle ground between `MIN_OUT_OF_POCKET` and `MIN_PITIA`: buys down the rate as much as possible given available cash to close but does not exhaust available assets. With `maxLTV`, yields [fixed structures](/guides/getting-started/pricing-optimizations/fixed-loan-structures) (e.g. 90% LTV). |

### Pricing response types

Pricing responses use the same type system whether you call the full rate sheet or the most-optimal-structure flow. Use this reference when handling **products**, **structures**, and **ineligibility or error details**.

#### Product-level results

Each product is either:

| Type                           | Description                                                                                                              |
| ------------------------------ | ------------------------------------------------------------------------------------------------------------------------ |
| **`EligibleProductPricing`**   | Product is eligible; it has a **`rateStack`** array of structures (each structure is eligible, ineligible, or an error). |
| **`IneligibleProductPricing`** | Product is not available as a whole; it has **`details`** (ineligibility reasons) and no `rateStack`.                    |

#### Structure-level results (`StructuringResult` union)

Each structure in a rate stack (or in most-optimal-structure's `productBreakdown`) is one of:

| Type                             | Description                                                                                                                                                 |
| -------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **`EligibleProductStructure`**   | Structure meets all constraints and guidelines; full pricing fields (rate, APR, [PITIA](/entity-models/key-concepts/piti), closing costs, etc.).            |
| **`IneligibleProductStructure`** | Structure fails one or more rules; same pricing fields plus **`ineligibilityDetails`** (violation types below).                                             |
| **`StructuringError`**           | Optimizer could not find a feasible structure; product/rate context plus **`unsatisfiabilityDetails`** (e.g. `GuidelineViolation`, `OptimizerUnsatisfied`). |

#### Structure ineligibility details (`IneligibleProductStructure.ineligibilityDetails`)

Each item is one of:

| Type                          | Description                                                                                          |
| ----------------------------- | ---------------------------------------------------------------------------------------------------- |
| **`DebtToIncomeViolation`**   | [DTI](/entity-models/key-concepts/dti) would exceed the allowed limit.                               |
| **`LoanToValueViolation`**    | [LTV](/entity-models/key-concepts/ltv) is outside the allowed range.                                 |
| **`QmFeeCapViolation`**       | Would violate the [Qualified Mortgage (QM)](/entity-models/key-concepts/qualified-mortgage) fee cap. |
| **`ReservesNotMetViolation`** | Does not meet [reserves](/entity-models/key-concepts/reserves) requirements.                         |

#### Structuring error details (`StructuringError.unsatisfiabilityDetails`)

| Type                       | Description                                                                                                                  |
| -------------------------- | ---------------------------------------------------------------------------------------------------------------------------- |
| **`GuidelineViolation`**   | A guideline was violated in a way that's represented as a general violation rather than a specific DTI/LTV/reserves/QM type. |
| **`OptimizerUnsatisfied`** | The optimizer could not satisfy the constraints (e.g., the problem is infeasible).                                           |

## Best practices

1. **Set appropriate objectives**: Choose the optimization objective that matches borrower priorities.

2. **Trust the optimization**: The system evaluates thousands of structures. Trust that it finds optimal solutions.

3. **Explain the value**: Help borrowers understand that optimized structures may differ from traditional percentages (3%, 20%) but provide better terms.

### Pricing optimization guides

Choose the right approach for your use case:

<CardGroup cols={3}>
  <Card title="Full rate sheet optimizations" icon="grid" href="/guides/getting-started/pricing-optimizations/full-rate-sheet">
    Show the full rate stack across all products—eligible structures and ineligible products/structures with their reasons.
  </Card>

  <Card title="Most optimal structure" icon="sparkles" href="/guides/getting-started/pricing-optimizations/most-optimal-structure">
    Get the single best structure for your objective (e.g. MIN\_PITIA). Optional Product Breakdown shows the best structure per product.
  </Card>

  <Card title="Fixed loan structures" icon="percent" href="/guides/getting-started/pricing-optimizations/fixed-loan-structures">
    Get a fixed structure (e.g. 90% LTV) by using MIN\_DOWN\_PAYMENT with maxLTV.
  </Card>
</CardGroup>

## Related resources

* [Pricing scenarios](/recipes/scenarios) - Show borrowers optimized pricing options
* [Complete integration guide](/guides/getting-started/e2e-build) - Build a full loan origination flow
* [Tracking loan updates](/recipes/loan-updates) - Track loan status and pricing changes