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

# Optimizer

> How the Giza Optimizer allocates capital across protocols

## What is the Optimizer?

The Optimizer is a stateless service that calculates optimal capital allocation across DeFi lending protocols. It looks at current APRs, gas costs, and constraints to find the distribution of capital with the highest net return.

## How It Works

```mermaid theme={null}
graph TD
    A[Input: Current State] --> B[Fetch Protocol APRs]
    A --> C[Get Gas Prices]
    A --> D[Load Constraints]

    B --> E[Optimization Engine]
    C --> E
    D --> E

    E --> F[Calculate Optimal Allocation]
    F --> G[Generate Action Plan]
    G --> H[Create Transaction Calldata]

    H --> I[Output: Optimization Result]
```

## Two Integration Patterns

### Automatic (Agentic)

Agents use the optimizer automatically on a continuous loop. You activate the agent and it handles optimization internally:

1. Agent calls optimizer with current allocations
2. Optimizer returns optimal allocation + action plan
3. Agent executes the rebalancing transactions
4. Repeat on regular optimization cycles

### Manual (IaaS)

Call the optimizer directly for custom implementations. You receive the optimal allocation and decide whether and when to execute. See the [IaaS Integration Guide](/developers/guides/iaas-integration) for a complete walkthrough.

## Stateless Design

The optimizer is **completely stateless**:

* No storage of historical data
* Each call is independent
* Same inputs return same outputs (for same market conditions)
* No side effects

This means it's predictable, testable, composable, and private -- Giza doesn't store your data.

## Optimization Algorithm

### Factors Considered

| Factor                       | Description                                                                                                                     |
| ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------- |
| **Protocol APRs**            | Real-time APRs from each protocol for the specific token, weighted by allocation size                                           |
| **Gas Costs**                | Estimated gas for each rebalancing transaction. Optimization only proceeds if APR improvement exceeds gas costs                 |
| **Protocol Liquidity**       | Available liquidity in each protocol. Won't allocate more than the protocol can efficiently handle                              |
| **Slippage**                 | Price impact of large deposits/withdrawals, especially for smaller protocols                                                    |
| **Constraints**              | User-defined constraints (min protocols, max per protocol, exclusions). See [Constraints](/developers/architecture/constraints) |
| **Transaction Minimization** | Prefers fewer, larger transactions over many small ones to save gas                                                             |

### Optimization Steps

1. **Fetch Data** -- Get current APRs, gas prices, liquidity
2. **Apply Constraints** -- Filter out invalid allocations
3. **Calculate Scores** -- Score each possible allocation
4. **Select Optimal** -- Choose highest net return allocation
5. **Generate Plan** -- Create minimal set of transactions
6. **Validate** -- Ensure plan respects all constraints

## Optimizer Output

The optimizer returns three things:

1. **Optimization Result** -- Optimal allocations, APR improvement, gas estimate, break-even days
2. **Action Plan** -- Step-by-step deposit/withdraw instructions to reach the optimal allocation
3. **Execution Calldata** -- Ready-to-execute transaction data (contract addresses, function calls, parameters)

See the [SDK Optimizer Reference](/sdk-reference/optimizer) for the full response types and code examples.

## Best Practices

* **Don't over-optimize** -- Calling too frequently wastes gas. Let APR differences accumulate. Good: every 6-24 hours. Bad: every 5 minutes.
* **Set APR thresholds** -- Only rebalance if improvement exceeds a threshold (e.g., 0.3%)
* **Use constraints** -- Always set constraints to match your risk tolerance
* **Consider gas prices** -- During high gas periods, higher APR improvement is needed to justify rebalancing

## Next Steps

<CardGroup cols={2}>
  <Card title="Constraints" icon="sliders" href="/developers/architecture/constraints">
    All constraint types for controlling optimization
  </Card>

  <Card title="SDK Optimizer Reference" icon="code" href="/sdk-reference/optimizer">
    Complete optimizer API with code examples
  </Card>

  <Card title="IaaS Integration" icon="brain" href="/developers/guides/iaas-integration">
    Use the optimizer with your own execution infrastructure
  </Card>

  <Card title="Quickstart" icon="rocket" href="/developers/quickstart">
    See the optimizer in action within a full integration
  </Card>
</CardGroup>