Manage shareholders

Approve or remove wallets that may hold MicroVault shares.

Add a wallet to the shareholder list before allowing it to subscribe or receive shares. Removing it blocks future subscriptions and incoming share transfers, but does not prevent it from redeeming shares it already owns.

The proof endpoint returns the onchain membership proof required by a subscription or share-transfer transaction. Ground updates the vault’s compact onchain allowlist when you add or remove an address.

Prerequisites

• An active VAULT_ID
• The shareholder’s EVM address
• uuidgen for idempotency keys

1. Add a shareholder

curl -sS -X PUT \
  "$GROUND_API/v2/microvaults/vaults/$VAULT_ID/shareholders/0x76f8fc6667e239f83a547d4e16225d6a34f6fa22" \
  -H "$AUTH" -H "Idempotency-Key: $(uuidgen)" -H 'Content-Type: application/json' -d '{}'

The response contains a task. Only one shareholder update can be in progress for a vault at a time.

2. Wait for the proof

curl -sS \
  "$GROUND_API/v2/microvaults/vaults/$VAULT_ID/shareholders/0x76f8fc6667e239f83a547d4e16225d6a34f6fa22/proof" \
  -H "$AUTH" | jq

A 404 means the wallet is not on the currently confirmed list. Poll until the proof is available before enabling subscription; the add task being accepted is not yet sufficient.

3. Remove a shareholder

curl -sS -X DELETE \
  "$GROUND_API/v2/microvaults/vaults/$VAULT_ID/shareholders/0x76f8fc6667e239f83a547d4e16225d6a34f6fa22" \
  -H "$AUTH" -H "Idempotency-Key: $(uuidgen)"

Removing a wallet prevents new subscriptions and transfers to that wallet. It does not erase shares the wallet already owns or prevent redemption.

Confirm access

The wallet is approved when the proof endpoint returns 200. Confirm removal by checking that the wallet no longer appears in GET /shareholders and its proof endpoint returns 404.