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

# How Auto Rebalancing Works

> Choose automatic or manual allocation and understand when Ground moves funds toward your portfolio targets.

An automatically rebalanced portfolio wallet maintains the allocation strategy you choose. Ground compares current holdings with your targets and moves funds when the difference is large enough and the required transactions can execute. Deposits, withdrawals, changes in position value, and strategy updates can all create a difference from the target.

## Two ways to manage a portfolio wallet

Choose the wallet's allocation behavior when you [create it](/api-reference/create-wallet):

|                         | Automatically rebalanced                                                                                                                 | Manually allocated                                                                                |
| ----------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------- |
| Creation setting        | `autoRebalance: true` with `strategy.allocations`                                                                                        | `autoRebalance: false`, with no `strategy`                                                        |
| Allocation instructions | Choose how much to hold in cash and each yield source, as percentages. Set USDC and USDT allocations separately; each group totals 100%. | Specify individual movements with `from`, `to`, and `amountUsd`.                                  |
| New deposits            | Arrive as cash, then become eligible for allocation toward the strategy.                                                                 | Remain cash until you request an allocation.                                                      |
| Changes in holdings     | Ground checks for drift and rebalances eligible amounts.                                                                                 | Ground does not automatically restore allocation percentages.                                     |
| How to make changes     | [Update Strategy](/docs/portfolio-wallets/update-strategy)                                                                               | [Preview Allocation](/api-reference/preview-allocation), then [Allocate](/api-reference/allocate) |
| Wallet response         | `autoRebalance: true` and populated `strategyAllocations`                                                                                | `autoRebalance: false` and `strategyAllocations: null`                                            |

If you provide a strategy and omit `autoRebalance`, automatic rebalancing is enabled. Choose automatic rebalancing when you want Ground to maintain a standing allocation; choose manual allocation when your application decides each movement.

Configured risk-exit actions are separate from ordinary allocation maintenance and can apply to either wallet type.

## How targets are calculated

Targets are grouped by stablecoin. The USDC allocations sum to 100% of the value in the USDC group, and the USDT allocations independently sum to 100% of the value in the USDT group. A rebalance stays within its token group. You can include `cash` as a target to keep part of that group uninvested.

Ground values yield positions in USD using their available balances and position prices, then calculates the desired dollar value of each target. Funds reserved for ongoing work are excluded from the amounts available to rebalance. A frozen holding that has been removed from the strategy is also excluded from the value that can be redistributed.

For example, with \$10,000 available in the USDC group and a 60% / 40% strategy, the desired position values are \$6,000 and \$4,000. Any USDT holdings are evaluated separately.

## When a rebalance happens

### Ordinary allocation drift

For each target, Ground calculates a dollar threshold:

```text theme={"theme":{"light":"github-light","dark":"github-dark"}}
Desired value = available value in the token group × target percentage
Drift threshold = greater of (2% × desired value) and the minimum rebalance amount
```

An overweight position can fund a rebalance when its excess is **at least** its threshold. An underweight position can receive funds when its shortfall is **at least** its own threshold. Both sides must qualify, and each planned movement must meet the minimum rebalance amount.

The default minimum rebalance amount is **\$1**. This is a service configuration, so it can differ by environment. The examples below use the \$1 default. Individual yield sources can also impose deposit minimums or allocation limits.

<Note>
  The 2% band is relative to the target's dollar value. For a \$6,000 target, it is \$120. In a \$10,000 token group, that corresponds to 1.2 percentage points of allocation weight.
</Note>

Once a movement qualifies, Ground plans toward the target amount. It does not move only the portion beyond the threshold. Small residual differences can remain because of rounding, minimums, or execution constraints.

### New cash and removed positions

Two common cases use a zero-percent target:

* **Cash with a 0% cash target:** available cash at or above the minimum can fund underweight targets without waiting for their usual 2% drift band. Each individual movement must still meet the minimum. If your strategy includes a positive cash target, ordinary drift thresholds apply to that cash allocation.
* **A yield position removed from the strategy or set to 0%:** a sellable balance at or above the minimum becomes eligible to exit. Receiving targets can accept the proceeds once their shortfalls meet the minimum, even if they are inside their usual drift bands.

A strategy update saves the new targets immediately. Actual movements happen later when eligible work is found; accepting the update does not mean funds have moved.

### Conditions that can defer or limit a rebalance

The periodic check considers active wallets with automatic rebalancing enabled and enough available value. It waits while a withdrawal or another rebalance remains open, and skips wallets whose rebalancing is frozen.

An eligible movement also needs usable position prices, a supported route, and permission to exit the source and enter the destination. Source controls and risk rules may block buying or selling. Deposit minimums and remaining allocation capacity may reduce the amount that can move or leave funds in cash.

Ground checks periodically; the default check interval is one minute. Wallets are processed in batches, so this is not a promise that every wallet starts or completes a rebalance within one minute. Completion also depends on chain confirmations, bridging, and the yield source's redemption or subscription process.

## Examples

These examples assume available funds, permitted routes, no active withdrawals or rebalances, and no additional source limits. Amounts are simplified to omit fees and rounding.

### Example 1: Drift in a 60% / 40% portfolio

A wallet has \$10,000 in its USDC group:

| Position | Target weight | Desired value | Drift threshold |
| -------- | ------------- | ------------- | --------------- |
| Source A | 60%           | \$6,000       | \$120           |
| Source B | 40%           | \$4,000       | \$80            |

If A holds **\$6,100** and B holds **\$3,900**, no movement is planned. B's \$100 shortfall meets its \$80 threshold, but A's \$100 excess is below its \$120 threshold.

If A instead holds **\$6,150** and B holds **\$3,850**, both qualify. Ground can move approximately **\$150 from A to B**, bringing them toward \$6,000 and \$4,000.

### Example 2: Investing a new deposit

The same 60% / 40% wallet is on target at \$6,000 in A and \$4,000 in B, with a 0% cash target. You deposit **\$10 USDC**.

The group's value becomes \$10,010. Its new targets are **\$6,006 in A** and **\$4,004 in B**, creating shortfalls of \$6 and \$4.

Those shortfalls are below the ordinary drift bands. However, the \$10 cash balance has a zero-percent target, so Ground can allocate **\$6 to A and \$4 to B**. Both movements meet the \$1 minimum.

A **\$1 deposit** in the same situation would produce shortfalls of \$0.60 and \$0.40. Neither movement meets the minimum, so the cash remains available for a later check after the balances or targets change.

### Example 3: Removing a small position

A wallet holds **\$9,990 in A** and **\$10 in B**. You update the strategy to 100% A, removing B.

B now has a zero-percent target. Its \$10 balance meets the minimum for an exit. A can receive the **\$10** even though its shortfall is below its ordinary \$200 drift threshold. The movement remains subject to B allowing redemptions and A allowing deposits.

## How the risk engine affects rebalancing

Risk rules determine whether Ground can continue allocating to a yield source or should exit it. Your saved strategy remains unchanged: a risk restriction can keep actual holdings away from their target weights for as long as the restriction applies.

Each rule has a configured condition and one of three outcomes:

| Outcome                                                         | Effect on rebalancing                                                                                                                                 |
| --------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
| Alert only (`alert`)                                            | Creates an alert. The alert itself does not block allocations or request an exit; ordinary rebalancing continues.                                     |
| Prevent additional allocation (`prevent_additional_allocation`) | Blocks new rebalance buys into the affected source. Existing holdings can remain invested, and permitted exits can still proceed.                     |
| Exit position (`exit_position`)                                 | Blocks new rebalance buys into the affected source and requests redemption of its available position into cash in the source's underlying stablecoin. |

The action depends on the rule's approval setting. An **automatic** block applies when the breach is detected, and an automatic exit is queued for execution. An **approval-required** block or exit waits for approval; that pending rule does not yet block new buys. Other active rules and source controls still apply.

### Risk exits take priority over allocation targets

A risk exit can act even when the portfolio is exactly on target. Its plan uses the affected source's available, unreserved balance rather than the ordinary 2% drift band or default \$1 rebalance minimum. Actual completion still depends on available funds, transaction execution, and the source's redemption process. A queued or started exit does not mean its proceeds have settled.

The exit sends proceeds to cash and leaves unrelated yield positions alone. It does not automatically distribute the exited source's target weight among the remaining sources. Subsequent ordinary rebalancing can still fund permitted sources toward their original targets; amounts that cannot be allocated remain in cash.

While an exit's buy restriction is active, ordinary rebalancing cannot buy back into the affected source. An approved exit that fails or needs a retry continues to block buys while its alert remains ongoing and its rule remains active.

Risk exits can also apply to manually allocated wallets. Those wallets still do not perform ordinary automatic allocation after the exit.

### Example: A blocked source receives no new allocation

Suppose an automatically rebalanced wallet holds **\$6,000 in A** and **\$4,000 in B**, matching its 60% / 40% USDC strategy, with a 0% cash target. An automatic rule now prevents additional allocation to A. You deposit **\$1,000 USDC**.

The new desired values are \$6,600 in A and \$4,400 in B. Assuming the other execution conditions are met, Ground can allocate **\$400 to B**. The **\$600 intended for A stays in cash** while A is blocked. A's existing \$6,000 remains invested; the block alone does not request its redemption.

Ground does not put the entire deposit into B. The saved 60% / 40% strategy still determines the targets.

If the same rule required approval, this block would take effect only after approval. If its outcome were alert only, it would not prevent the usual \$600 / \$400 allocation.

### Example: An on-target position is exited to cash

Start again with **\$6,000 in A** and **\$4,000 in B**, no cash, and the same 60% / 40% strategy. This time, an automatic rule requests an exit from A.

Even though allocation drift is zero, Ground requests redemption of A's available position. After settlement, and ignoring fees or price changes, the wallet holds **\$6,000 USDC cash** and **\$4,000 in B**. The exit does not sell B or move A's proceeds into B. The ongoing exit restriction prevents the ordinary rebalance process from buying A again.

### What happens when the risk condition recovers?

When a later risk evaluation observes that the condition has recovered, Ground resolves that alert and removes its associated buy restriction. Other active restrictions can still block the source.

For an automatically rebalanced wallet, the saved strategy becomes actionable again subject to the usual thresholds and execution conditions. In the exit example, if A becomes eligible again after the exit has settled, Ground can allocate the \$6,000 cash back into A. **A risk exit does not permanently remove a source from your strategy.** Update the strategy if you want to keep that source excluded after recovery.

For a manually allocated wallet, recovery permits future allocation requests but does not automatically reinvest the cash.

## Monitor the result

Use [Get Wallet](/api-reference/get-wallet) to compare `strategyAllocations` with actual `positions[].valueUsd`. Target weights are returned as `targetWeightBps`, where 10,000 basis points equals 100%.

While a rebalance runs, the wallet can report `rebalance_active` or `withdrawal_and_rebalance_active`. `balance.reservedUsd` identifies customer-owned value reserved for ongoing work. See [Balances and Yield](/docs/portfolio-wallets/balances-and-yield) and [Polling](/docs/portfolio-wallets/polling) for interpreting these fields.

An `idle` wallet can still be slightly off target because its differences are below the thresholds or no eligible movement is available. If a larger difference persists, check for active work, source availability, and applicable minimums or limits. Contact Ground support with the wallet ID if the reason is unclear.