> ## 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.

# Optimize Allocations

> Calculate optimal capital allocation across protocols

<Note>
  **SDK Alternative**: Use `giza.optimize(options)` for a simpler TypeScript interface. [See SDK docs](/sdk-reference/optimizer)
</Note>

## Description

Calculates the optimal capital allocation across DeFi lending protocols. Returns the optimal allocation, an action plan to achieve it, and execution-ready calldata.

This endpoint is the core of the **IaaS (Intelligence as a Service)** integration.

## Path Parameters

<ParamField path="chain_id" type="integer" required>
  The blockchain chain ID
</ParamField>

## Request Body

<ParamField body="total_capital" type="string" required>
  Total capital to allocate (as bigint string, e.g., "1000000000" for 1000 USDC)
</ParamField>

<ParamField body="token_address" type="string" required>
  Token address to optimize for
</ParamField>

<ParamField body="current_allocations" type="object" required>
  Current allocations by protocol (protocol name → amount as bigint string)

  Example: `{"aave": "500000000", "compound": "500000000"}`
</ParamField>

<ParamField body="protocols" type="array" required>
  List of protocol names to consider for optimization
</ParamField>

<ParamField body="constraints" type="array">
  Optional constraints for optimization. Each constraint is an object with `kind` and `params`.

  **Constraint types and required parameters:**

  | Kind                                 | Params                                                               | Description                                         |
  | ------------------------------------ | -------------------------------------------------------------------- | --------------------------------------------------- |
  | `min_protocols`                      | `min_protocols` (int), `min_fraction_per_protocol` (float, optional) | Minimum number of protocols to use                  |
  | `max_amount_per_protocol`            | `protocol` (string), `max_ratio` (float 0-1)                         | Cap a protocol at a **percentage** of total capital |
  | `max_allocation_amount_per_protocol` | `protocol` (string), `max_amount` (int)                              | Cap a protocol at an **absolute amount**            |
  | `min_amount`                         | `min_amount` (int)                                                   | Minimum amount for any used protocol                |
  | `min_allocation_amount_per_protocol` | `protocol` (string), `min_amount` (int)                              | Minimum amount for a specific protocol              |
  | `exclude_protocol`                   | `protocol` (string)                                                  | Exclude a protocol from optimization                |

  **Example:**

  ```json theme={null}
  [
    { "kind": "min_protocols", "params": { "min_protocols": 2 } },
    { "kind": "max_amount_per_protocol", "params": { "protocol": "aave", "max_ratio": 0.5 } },
    { "kind": "exclude_protocol", "params": { "protocol": "compound" } }
  ]
  ```
</ParamField>

<ParamField body="wallet_address" type="string">
  Optional wallet address that will execute the transactions.
  Example: `"0x1234567890123456789012345678901234567890"`
</ParamField>

## Response

<ResponseField name="optimization_result" type="object">
  Optimization results

  <Expandable>
    <ResponseField name="allocations" type="array">
      List of protocol allocations with `protocol`, `allocation`, and `apr`
    </ResponseField>

    <ResponseField name="total_costs" type="number">
      Estimated gas costs
    </ResponseField>

    <ResponseField name="weighted_apr_initial" type="number">
      Initial weighted APR before optimization
    </ResponseField>

    <ResponseField name="weighted_apr_final" type="number">
      Final weighted APR after optimization
    </ResponseField>

    <ResponseField name="apr_improvement" type="number">
      APR improvement percentage
    </ResponseField>

    <ResponseField name="gas_estimate_usd" type="number">
      Estimated total gas cost in USD for executing the rebalancing (optional)
    </ResponseField>

    <ResponseField name="break_even_days" type="number">
      Number of days until APR improvement exceeds gas cost (optional)
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="action_plan" type="array">
  Ordered list of actions to execute

  <Expandable>
    <ResponseField name="action_type" type="string">
      `deposit` or `withdraw`
    </ResponseField>

    <ResponseField name="protocol" type="string">
      Target protocol
    </ResponseField>

    <ResponseField name="amount" type="string">
      Amount (bigint string)
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="calldata" type="array">
  Execution-ready transaction data

  <Expandable>
    <ResponseField name="contract_address" type="string">
      Target contract
    </ResponseField>

    <ResponseField name="function_name" type="string">
      Function to call
    </ResponseField>

    <ResponseField name="parameters" type="array">
      ABI-encoded parameters
    </ResponseField>

    <ResponseField name="value" type="string">
      Native token value
    </ResponseField>

    <ResponseField name="protocol" type="string">
      Protocol reference
    </ResponseField>

    <ResponseField name="description" type="string">
      Human-readable description
    </ResponseField>
  </Expandable>
</ResponseField>

<RequestExample>
  ```bash cURL (Basic) theme={null}
  curl -X POST "https://partners-backend-1038109371738.europe-west1.run.app/api/v1/optimizer/8453/optimize" \
    -H "Content-Type: application/json" \
    -H "X-Partner-API-Key: your-api-key" \
    -H "X-Partner-Name: your-partner-name" \
    -d '{
      "total_capital": "1000000000",
      "token_address": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
      "current_allocations": {
        "aave": "500000000",
        "compound": "500000000"
      },
      "protocols": ["aave", "compound", "moonwell", "fluid"],
      "wallet_address": "0x1234567890123456789012345678901234567890"
    }'
  ```

  ```bash cURL (With Constraints) theme={null}
  curl -X POST "https://partners-backend-1038109371738.europe-west1.run.app/api/v1/optimizer/8453/optimize" \
    -H "Content-Type: application/json" \
    -H "X-Partner-API-Key: your-api-key" \
    -H "X-Partner-Name: your-partner-name" \
    -d '{
      "total_capital": "1000000000",
      "token_address": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
      "current_allocations": {
        "aave": "500000000",
        "compound": "500000000"
      },
      "protocols": ["aave", "compound", "moonwell", "fluid"],
      "wallet_address": "0x1234567890123456789012345678901234567890",
      "constraints": [
        { "kind": "min_protocols", "params": { "min_protocols": 2 } },
        { "kind": "max_amount_per_protocol", "params": { "protocol": "aave", "max_ratio": 0.5 } },
        { "kind": "max_amount_per_protocol", "params": { "protocol": "compound", "max_ratio": 0.5 } },
        { "kind": "max_amount_per_protocol", "params": { "protocol": "moonwell", "max_ratio": 0.5 } },
        { "kind": "max_amount_per_protocol", "params": { "protocol": "fluid", "max_ratio": 0.5 } }
      ]
    }'
  ```

  ```javascript JavaScript theme={null}
  const response = await fetch(
    'https://partners-backend-1038109371738.europe-west1.run.app/api/v1/optimizer/8453/optimize',
    {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        'X-Partner-API-Key': 'your-api-key',
        'X-Partner-Name': 'your-partner-name',
      },
      body: JSON.stringify({
        total_capital: '1000000000',
        token_address: '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913',
        current_allocations: {
          aave: '500000000',
          compound: '500000000',
        },
        protocols: ['aave', 'compound', 'moonwell', 'fluid'],
        wallet_address: '0x1234567890123456789012345678901234567890',
        constraints: [
          { kind: 'min_protocols', params: { min_protocols: 2 } },
          { kind: 'max_amount_per_protocol', params: { protocol: 'fluid', max_ratio: 0.5 } }
        ]
      }),
    }
  );
  const data = await response.json();
  ```

  ```python Python theme={null}
  import requests

  response = requests.post(
      'https://partners-backend-1038109371738.europe-west1.run.app/api/v1/optimizer/8453/optimize',
      headers={
          'X-Partner-API-Key': 'your-api-key',
          'X-Partner-Name': 'your-partner-name',
      },
      json={
          'total_capital': '1000000000',
          'token_address': '0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913',
          'current_allocations': {
              'aave': '500000000',
              'compound': '500000000',
          },
          'protocols': ['aave', 'compound', 'moonwell', 'fluid'],
          'wallet_address': '0x1234567890123456789012345678901234567890',
          'constraints': [
              {'kind': 'min_protocols', 'params': {'min_protocols': 2}},
              {'kind': 'max_amount_per_protocol', 'params': {'protocol': 'fluid', 'max_ratio': 0.5}}
          ]
      }
  )
  data = response.json()
  ```
</RequestExample>

<ResponseExample>
  ```json 200 OK theme={null}
  {
    "optimization_result": {
      "allocations": [
        {
          "protocol": "aave",
          "allocation": "700000000",
          "apr": 5.5
        },
        {
          "protocol": "compound",
          "allocation": "300000000",
          "apr": 4.8
        }
      ],
      "total_costs": 0.05,
      "weighted_apr_initial": 5.0,
      "weighted_apr_final": 5.29,
      "apr_improvement": 5.8,
      "gas_estimate_usd": 2.50,
      "break_even_days": 15.3
    },
    "action_plan": [
      {
        "action_type": "withdraw",
        "protocol": "compound",
        "amount": "200000000",
        "underlying_amount": "200000000"
      },
      {
        "action_type": "deposit",
        "protocol": "aave",
        "amount": "200000000"
      }
    ],
    "calldata": [
      {
        "contract_address": "0xA88594D404727625A9437C3f886C7643872296AE",
        "function_name": "withdraw",
        "parameters": ["200000000"],
        "value": "0",
        "protocol": "compound",
        "description": "Withdraw 200000000 from Compound"
      },
      {
        "contract_address": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
        "function_name": "approve",
        "parameters": ["0x9c4ec768c28520B50860ea7a15bd7213a9fF58bf", "200000000"],
        "value": "0",
        "protocol": "aave",
        "description": "Approve USDC for Aave"
      },
      {
        "contract_address": "0x9c4ec768c28520B50860ea7a15bd7213a9fF58bf",
        "function_name": "supply",
        "parameters": ["0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", "200000000", "0x0000000000000000000000000000000000000000", "0"],
        "value": "0",
        "protocol": "aave",
        "description": "Deposit 200000000 to Aave"
      }
    ]
  }
  ```

  ```json 400 Bad Request theme={null}
  {
    "detail": "Invalid input parameters"
  }
  ```
</ResponseExample>