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

# Create a MicroVault

> Prepare, authorize, and confirm a new MicroVault deployment.

Creating a MicroVault deploys a non-upgradeable vault and its ERC-20 share token. The vault address is also the share-token address.

## Prerequisites

* Completed [organization onboarding](/docs/microvaults/onboarding)
* The `CUSTOMER_ID` returned by `GET /v2/microvaults/customers`
* A unique base-10 integer `customerVaultNonce`
* The Ethereum Sepolia base-asset address
* A fee-recipient EVM address and fee rates expressed in basis points

```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 CREATE_REQUEST_ID="$(uuidgen)"
```

## 1. Prepare the deployment

One basis point is `0.01%`; `100` basis points is `1%`. Use `0` for no management or performance fee.

```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: $CREATE_REQUEST_ID" \
  -d '{
    "action": "create_vault",
    "parameters": {
      "customerVaultNonce": "1",
      "baseAsset": "0x1c7d4b196cb0c7b01d743fbc6116a902379c7238",
      "name": "Acme Treasury MicroVault",
      "symbol": "acmeUSDC",
      "feeRecipient": "0x1111111111111111111111111111111111111111",
      "managementFeeBps": 0,
      "performanceFeeBps": 0
    }
  }'
```

A `201` response means the action was prepared and simulated. Save its `id` as `INTENT_ID`. Reusing the idempotency key is valid only for an identical retry.

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "id": "4f36d486-58c9-441b-8535-6097ad3f1832",
  "status": "prepared",
  "simulation": { "ok": true },
  "turnkeyActivityId": "activity-id-or-null"
}
```

## 2. Authorize the deployment

When `turnkeyActivityId` is present, the managed authority approval has already started. Poll the authorization endpoint. When it is null, sign the returned EIP-712 `signingPayload` with the required authority and submit the signature:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl -sS -X POST "$GROUND_API/v2/microvaults/authorizations/$INTENT_ID/relay" \
  -H "$AUTH" \
  -H 'Content-Type: application/json' \
  -d '{"signature":"0x..."}'
```

The relay returns `202` when it accepts the transaction for submission. That is not yet onchain confirmation.

## 3. Wait for confirmation

```javascript theme={"theme":{"light":"github-light","dark":"github-dark"}}
async function waitForAuthorization(intentId) {
  for (;;) {
    const response = await fetch(
      `${process.env.GROUND_API}/v2/microvaults/authorizations/${intentId}`,
      { headers: { Authorization: `Bearer ${process.env.GROUND_API_KEY}` } },
    );
    if (!response.ok) throw new Error(await response.text());
    const result = await response.json();
    if (["confirmed", "executed"].includes(result.status)) return result;
    if (["rejected", "superseded", "expired"].includes(result.status)) {
      throw new Error(`Vault deployment ended with ${result.status}`);
    }
    await new Promise((resolve) => setTimeout(resolve, 1500));
  }
}
```

## 4. Wait for the vault to become active

The list endpoint reports the deployment under `provisionings` while the vault is being indexed. It then moves to `items`.

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

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "items": [],
  "nextCursor": null,
  "provisionings": [
    {
      "id": "4f36d486-58c9-441b-8535-6097ad3f1832",
      "chainId": 11155111,
      "address": "0x2222222222222222222222222222222222222222",
      "shareName": "Acme Treasury MicroVault",
      "shareSymbol": "acmeUSDC",
      "status": "provisioning",
      "error": null
    }
  ]
}
```

## Confirm creation

Creation is complete when the authorization is confirmed and the vault appears in `items` with `status: "active"`. Save the vault `id` and `address`.

The new vault starts with 100% of its assets in idle USDC. Setting a target allocation later does not itself move assets; the rebalance workflow performs the movement.

If a provisioning entry changes to `failed`, read its `error` and create a new vault with a new nonce and idempotency key after correcting the cause. Do not reuse a nonce from a failed or confirmed deployment.