Manage shareholders

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

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

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

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.

{
  "draft": {
    "root": "0x1111111111111111111111111111111111111111111111111111111111111111",
    "addresses": [
      "0x3333333333333333333333333333333333333333",
      "0x4444444444444444444444444444444444444444"
    ]
  }
}

3. Publish the root

Prepare a set_shareholder_root authorization with a new idempotency key:

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

curl -sS \
  "$GROUND_API/v2/microvaults/vaults/$VAULT_ID/shareholders/$WALLET_ADDRESS/proof" \
  -H "$AUTH"

{
  "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.

Getting Started

Vault Lifecycle

Operations

Resources

Manage shareholders

Prerequisites

1. Read the current list

2. Replace the draft

3. Publish the root

4. Fetch the active proof

Confirm access

​Prerequisites

​1. Read the current list

​2. Replace the draft

​3. Publish the root

​4. Fetch the active proof

​Confirm access

Prerequisites

1. Read the current list

2. Replace the draft

3. Publish the root

4. Fetch the active proof

Confirm access