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

# MicroVault quickstart

> Create and inspect a sandbox MicroVault.

<Note>
  MicroVaults are in private preview for enabled sandbox organizations on Ethereum Sepolia.
</Note>

## Prerequisites

* A sandbox organization with MicroVaults enabled
* A Ground sandbox API key
* `curl`, `jq`, and `uuidgen`

```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"
```

## 1. Complete onboarding

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl -sS -X POST "$GROUND_API/v2/microvaults/onboarding" \
  -H "$AUTH" -H 'Content-Type: application/json' -d '{}'

AUTHORITY_RESPONSE=$(curl -sS "$GROUND_API/v2/microvaults/managed-authority" -H "$AUTH")
echo "$AUTHORITY_RESPONSE" | jq
AUTHORITY_ADDRESS=$(echo "$AUTHORITY_RESPONSE" | jq -r '.authorityAddress')

CUSTOMER_ID=$(curl -sS "$GROUND_API/v2/microvaults/customers" -H "$AUTH" \
  | jq -r '.customers[] | select(.chainId == 11155111 and .status == "accepted") | .id' \
  | head -1)
test -n "$AUTHORITY_ADDRESS" -a "$AUTHORITY_ADDRESS" != "null"
test -n "$CUSTOMER_ID" && echo "$CUSTOMER_ID"
```

Continue when onboarding is `active`, the managed authority is `ready`, and `CUSTOMER_ID` is non-empty. If setup is still progressing, repeat these reads after a short delay. The onboarding request is idempotent.

## 2. Create the vault

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
export CREATE_REQUEST_ID="$(uuidgen)"
export RUN_ID="$(date +%s)"
export VAULT_NAME="Quickstart MicroVault $RUN_ID"

CREATE_PAYLOAD=$(jq -n \
  --arg nonce "$RUN_ID" \
  --arg name "$VAULT_NAME" \
  --arg feeRecipient "$AUTHORITY_ADDRESS" \
  '{action:"create_vault",parameters:{customerVaultNonce:$nonce,baseAsset:"0x1c7d4b196cb0c7b01d743fbc6116a902379c7238",name:$name,symbol:"mvUSDC",feeRecipient:$feeRecipient,managementFeeBps:0,performanceFeeBps:0}}')

CREATE_RESPONSE=$(curl -sS -X POST \
  "$GROUND_API/v2/microvaults/customers/$CUSTOMER_ID/authorizations" \
  -H "$AUTH" -H 'Content-Type: application/json' \
  -H "Idempotency-Key: $CREATE_REQUEST_ID" \
  -d "$CREATE_PAYLOAD")

echo "$CREATE_RESPONSE" | jq
export INTENT_ID=$(echo "$CREATE_RESPONSE" | jq -r '.id')
```

The response prepares and simulates a `create_vault` authorization. When `turnkeyActivityId` is present, approval has already started through the managed authority. Otherwise, sign the returned `signingPayload` and submit the signature to `POST /v2/microvaults/authorizations/{intentId}/relay`.

## 3. Wait for the vault to become active

Poll the authorization until it is `confirmed` or `executed`:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl -sS "$GROUND_API/v2/microvaults/authorizations/$INTENT_ID" -H "$AUTH" | jq
```

Then poll the vault list. The new vault first appears under `provisionings` and moves to `items` when it is active.

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

VAULT_ID=$(curl -sS "$GROUND_API/v2/microvaults/vaults" -H "$AUTH" \
  | jq -r --arg name "$VAULT_NAME" '.items[] | select(.shareName == $name and .status == "active") | .id' \
  | head -1)
test -n "$VAULT_ID" && echo "$VAULT_ID"
```

## 4. Inspect the vault

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl -sS "$GROUND_API/v2/microvaults/vaults/$VAULT_ID" -H "$AUTH" | jq
curl -sS "$GROUND_API/v2/microvaults/vaults/$VAULT_ID/sources" -H "$AUTH" | jq
curl -sS "$GROUND_API/v2/microvaults/vaults/$VAULT_ID/activity" -H "$AUTH" | jq
curl -sS "$GROUND_API/v2/microvaults/vaults/$VAULT_ID/performance-series" -H "$AUTH" | jq
```

## Confirm the quickstart

The quickstart is complete when the vault appears in `items` with `status: "active"` and the detail endpoint returns its contract address. A new vault has no shareholder assets until a wallet subscribes.

If the authorization reaches `rejected`, `superseded`, or `expired`, correct the reported error and create a new request with a new nonce and idempotency key. If provisioning reports `failed`, use its error before retrying. Continue with [Manage shareholders](/docs/microvaults/shareholders), [Configure strategy](/docs/microvaults/strategy), and [Subscribe from an external wallet](/docs/microvaults/subscribe).