Configure strategy and source modes

Strategy configuration has two parts: a mode that controls whether the vault may enter or exit each source, and target weights that guide rebalancing.

Prerequisites

An active MicroVault VAULT_ID
Its MicroVault account CUSTOMER_ID
A target allocation that totals no more than 10000 basis points; the remainder stays in idle USDC

export GROUND_API="https://sandbox.groundtech.co"
export GROUND_API_KEY="..."
export AUTH="Authorization: Bearer $GROUND_API_KEY"
export CUSTOMER_ID="8ef3d494-7b6f-4df4-9d45-09f31196368f"
export VAULT_ID="d9902b20-6499-4465-a4c3-5d2208182f79"

1. Discover admitted sources

curl -sS "$GROUND_API/v2/microvaults/yield-sources?chainId=11155111" -H "$AUTH"

Use sourceId values from this response. Fetch the catalog at runtime because source availability and APYs can change.

2. Set each source mode

Choose the mode based on the movement you want to allow:

Mode	New allocations	Exits
`active`	Allowed	Allowed
`buy_only`	Allowed	Blocked
`sell_only`	Blocked	Allowed
`disabled`	Blocked	Blocked

Prepare one authorization for each changed source:

curl -sS -X POST "$GROUND_API/v2/microvaults/customers/$CUSTOMER_ID/authorizations" \
  -H "$AUTH" \
  -H 'Content-Type: application/json' \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "action": "set_source_mode",
    "vaultId": "'"$VAULT_ID"'",
    "parameters": {
      "sourceId": "0x1111111111111111111111111111111111111111111111111111111111111111",
      "mode": "active"
    }
  }'

Authorize the returned payload and wait for confirmation before relying on the new mode.

3. Set target allocations

This example targets 60% in one source and 30% in another. The unlisted 10% becomes the idle-USDC target.

curl -sS -X POST "$GROUND_API/v2/microvaults/customers/$CUSTOMER_ID/authorizations" \
  -H "$AUTH" \
  -H 'Content-Type: application/json' \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
    "action": "set_allocation_targets",
    "authorizationMode": "customer",
    "vaultId": "'"$VAULT_ID"'",
    "parameters": {
      "sourceIds": [
        "0x1111111111111111111111111111111111111111111111111111111111111111",
        "0x2222222222222222222222222222222222222222222222222222222222222222"
      ],
      "targetBps": [6000, 3000]
    }
  }'

The arrays are positional: each targetBps value applies to the source at the same index. Omit zero-weight sources. No more than eight sources may have non-zero targets.

4. Wait for the rebalance

The confirmed target update changes the desired portfolio. Ground then moves idle assets and existing positions toward those targets, subject to source modes and source settlement times.

curl -sS "$GROUND_API/v2/microvaults/vaults/$VAULT_ID/sources" -H "$AUTH"
curl -sS "$GROUND_API/v2/microvaults/vaults/$VAULT_ID/activity" -H "$AUTH"

Do not treat authorization confirmation as rebalance completion. Track the rebalance activity and source positions until the activity is confirmed and in-flight source amounts have cleared.

Confirm the strategy

Verify that the vault detail reports the intended allocation targets, each source reports the intended mode, and the latest rebalance has completed. If a rebalance cannot enter or exit a source, check its vault-level mode and current global availability before changing the target again.

Getting Started

Vault Lifecycle

Operations

Resources

Configure strategy and source modes

Prerequisites

1. Discover admitted sources

2. Set each source mode

3. Set target allocations

4. Wait for the rebalance

Confirm the strategy

​Prerequisites

​1. Discover admitted sources

​2. Set each source mode

​3. Set target allocations

​4. Wait for the rebalance

​Confirm the strategy

Prerequisites

1. Discover admitted sources

2. Set each source mode

3. Set target allocations

4. Wait for the rebalance

Confirm the strategy