> ## 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 fee wrappers

> Provision, retrieve, and update a fee wrapper over an existing gVault.

A fee wrapper is an organization-specific contract over an existing gVault. It
adds performance-fee accounting and its own customer allowlist. Provisioning a
wrapper does not create the underlying gVault.

## Provision a wrapper

Select a `gVaultId` from the gVault catalogue and generate a UUID v4:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl -X POST https://sandbox.groundtech.co/v2/fee-wrappers \
  -H "Authorization: Bearer $GROUND_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "requestId": "2b8332ce-5fe8-4fa6-a1da-d30a78285e07",
    "gVaultId": "ground-ustb-vault",
    "feeRecipientAddress": "0x92E6A1eD742f0C8502F902C61775F57728985b42",
    "performanceFeeBps": 2000
  }'
```

`performanceFeeBps` is the share of gains above the high-water mark paid to the
fee recipient. `2000` is 20%. The initial rate is also the wrapper's permanent
maximum; creating it with zero prevents enabling a performance fee later.

Use the same `requestId` when retrying the same logical request. Reusing it with
different parameters returns `409 request_id_conflict`.

## Wait for readiness

The create call returns `202` while provisioning is in progress. Poll the
resource:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl \
  https://sandbox.groundtech.co/v2/fee-wrappers/8f4c52d7-62ab-4db9-a964-92f481f6b851 \
  -H "Authorization: Bearer $GROUND_API_KEY"
```

Do not send customer transactions until `status` is `ready`. At that point,
persist both `id` for API calls and `contractAddress` for onchain calls.
Ground has also authorized the wrapper against its underlying gVault.

If your original response was lost, recover by provisioning request:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl \
  "https://sandbox.groundtech.co/v2/fee-wrappers?requestId=2b8332ce-5fe8-4fa6-a1da-d30a78285e07" \
  -H "Authorization: Bearer $GROUND_API_KEY"
```

## Update the fee configuration

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl -X PATCH \
  https://sandbox.groundtech.co/v2/fee-wrappers/8f4c52d7-62ab-4db9-a964-92f481f6b851/fees \
  -H "Authorization: Bearer $GROUND_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "feeRecipientAddress": "0x4444444444444444444444444444444444444444",
    "performanceFeeBps": 1500
  }'
```

Omit a field to leave it unchanged. The contract accrues fees under the old
configuration before applying the update. The new rate cannot exceed
`maxPerformanceFeeBps`.

API reference:
[provision](/api-reference/create-fee-wrapper),
[list](/api-reference/list-fee-wrappers),
[get](/api-reference/get-fee-wrapper), and
[update fees](/api-reference/update-fee-wrapper-fees).