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

# Nest Calculate Rebalance

Calculate optimal vault rebalancing based on APY-weighted allocation strategy. Takes current balances and vault APYs as input, outputs withdrawals and deposits needed. Ideal for: automated rebalancing, yield optimization, portfolio management workflows.

![Nest Calculate Rebalance logo](https://cdn.b3.fun/b3os-icons/plume.svg)
Catalog action Utility

Calculate optimal vault rebalancing based on APY-weighted allocation strategy. Takes current balances and vault APYs as input, outputs withdrawals and deposits needed. Ideal for: automated rebalancing, yield optimization, portfolio management workflows.


## At a Glance

| Field | Value |
| --- | --- |
| Action ID | `nest-calculate-rebalance` |
| Category | Utility |
| Connector | Not required |
| Requires gas | No |
| Funds movement | None declared |
| Tags | `defi`, `plume`, `nest`, `rebalancing`, `strategy`, `utility`, `calculation` |

## Payload Schema

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `balances` | `array` | Yes | Token balances from nest-detect-balance output. |
| `vaultApys` | `array` | Yes | Vault APY data from nest-get-vault-apys output. |
| `minApyDifferential` | `number` | No | Minimum APY differential per withdrawal to trigger rebalancing \(default: 0.01 = 1%\). |
| `maxAllocationPercent` | `number` | No | Maximum allocation per vault as decimal \(default: 0.50 = 50%\). |
| `minAllocationPercent` | `number` | No | Minimum allocation per vault to include \(default: 0.05 = 5%\). |
| `minRebalanceValuePusd` | `number` | No | Minimum pUSD value of a withdrawal/deposit to execute \(default: 10\). |
| `circuitBreakerThreshold` | `number` | No | Max allowed ratio of \|apy7d - apy30d\| / \|apy30d\| before excluding a vault \(default: 2.0\). |

## Result Schema

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `needsRebalance` | `boolean` | Yes | Whether any rebalancing is needed. |
| `hasWithdrawals` | `boolean` | Yes | Whether any withdrawals are needed. |
| `withdrawals` | `array` | Yes | List of withdrawal operations needed. |
| `deposits` | `array` | Yes | List of deposit operations needed. |
| `currentAllocation` | `object` | No | Current allocation breakdown \(symbol -> percentage\). |
| `targetAllocation` | `object` | No | Target allocation \(symbol -> percentage\). |
| `eligibleVaults` | `array` | No | Vaults that passed guard rails. |
| `excludedVaults` | `array` | No | Vaults excluded with reasons. |
| `retryArray` | `array` | Yes | Array of 50 zeros for retry polling loop \(for-each, max ~12.5h\). $item is unused. |
| `summary` | `string` | No | Human-readable summary of the rebalancing decision. |

## Examples

**Workflow node**

```json
{
  "type": "nest-calculate-rebalance",
  "payload": {
    "balances": [],
    "vaultApys": []
  },
  "children": []
}
```
  **Test with API**

```bash
curl -X POST "https://api.b3os.org/v1/actions/nest-calculate-rebalance/test" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "inputs": {
    "balances": [],
    "vaultApys": []
  }
}'
```

**Use expressions for dynamic values**

Payload fields can use workflow expressions such as `{{$trigger.body.amount}}`, `{{$nodes.fetch.result.price}}`, and `{{$props.asset}}` when the value should come from a trigger, prior node, or reusable workflow prop.