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

# Manage shareholders

> Publish the wallets permitted to subscribe to and hold MicroVault shares.

Each subscription includes a proof that both the caller and share recipient are on the vault's active shareholder allowlist. Updating the draft alone does not grant access; the new root must be authorized and confirmed onchain.

## Prerequisites

* An active MicroVault `VAULT_ID`
* Its MicroVault account `CUSTOMER_ID`
* Every wallet that should remain approved, because the update replaces the complete list

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
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"
export WALLET_ADDRESS="0x3333333333333333333333333333333333333333"
```

## 1. Read the current list

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl -sS "$GROUND_API/v2/microvaults/vaults/$VAULT_ID/shareholders" -H "$AUTH"
```

Start from the returned `shareholders.addresses`, add or remove addresses, then send the full replacement list in the next step. Omitting an existing address removes it when the new root is published.

## 2. Replace the draft

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl -sS -X PUT "$GROUND_API/v2/microvaults/vaults/$VAULT_ID/shareholders/draft" \
  -H "$AUTH" \
  -H 'Content-Type: application/json' \
  -d '{
    "addresses": [
      "0x3333333333333333333333333333333333333333",
      "0x4444444444444444444444444444444444444444"
    ]
  }'
```

Save `draft.root` from the response.

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "draft": {
    "root": "0x1111111111111111111111111111111111111111111111111111111111111111",
    "addresses": [
      "0x3333333333333333333333333333333333333333",
      "0x4444444444444444444444444444444444444444"
    ]
  }
}
```

## 3. Publish the root

Prepare a `set_shareholder_root` authorization with a new idempotency key:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
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_shareholder_root",
    "authorizationMode": "customer",
    "vaultId": "'"$VAULT_ID"'",
    "parameters": {
      "root": "0x1111111111111111111111111111111111111111111111111111111111111111"
    }
  }'
```

If managed approval starts, poll the returned authorization ID. Otherwise, sign its EIP-712 payload and submit the signature to `POST /v2/microvaults/authorizations/{intentId}/relay`. Wait until the authorization is `confirmed` or `executed`.

## 4. Fetch the active proof

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl -sS \
  "$GROUND_API/v2/microvaults/vaults/$VAULT_ID/shareholders/$WALLET_ADDRESS/proof" \
  -H "$AUTH"
```

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "proof": {
    "version": "1",
    "root": "0x1111111111111111111111111111111111111111111111111111111111111111",
    "walletAddress": "0x3333333333333333333333333333333333333333",
    "leafHash": "0x2222222222222222222222222222222222222222222222222222222222222222",
    "proof": ["0x3333333333333333333333333333333333333333333333333333333333333333"]
  }
}
```

Use the returned proof in the wallet's `depositWithProof` transaction.

## Confirm access

The wallet is approved when its proof endpoint returns `200` and the returned `root` matches the active root from the shareholders endpoint. A `404` means the wallet is not part of the active root yet; continue polling after publication or correct the full address list and publish a new root.