> ## 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 a gtoken's existing backing vault.

A fee wrapper is an organization-specific contract over a gtoken's existing backing vault. It
adds management and performance fees and its own customer allowlist. Provisioning a
wrapper does not create the underlying vault.

Set `GVAULT_ID` to the `id` selected from `GET /v2/gvaults/yield-sources`:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
export GVAULT_ID="ground-ustb-vault"
```

## Provision a wrapper

Select a `gVaultId` from the gtoken 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": "'$GVAULT_ID'",
    "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`.

To charge an annual management fee, include `"managementFeeBps": 10` in the
create request for 0.10% annually. The optional rate defaults to zero and accepts
integers from 0 through 100. Ground sets the cap to 100 bps (1.00%); do not pass
`maxManagementFeeBps`. Both fee types use `feeRecipientAddress`.

GET and list responses include `managementFeeBps` and read-only
`maxManagementFeeBps`. Older wrappers retain their original deployed caps.

## Provisioning statuses

| Status         | Meaning                                                                    | Application action                                                 |
| -------------- | -------------------------------------------------------------------------- | ------------------------------------------------------------------ |
| `provisioning` | Ground accepted the request, but deployment or configuration is incomplete | Persist the IDs and wait                                           |
| `ready`        | The wrapper is deployed and authorized against its backing vault           | Enable customer access and onchain use                             |
| `failed`       | Provisioning reached a terminal failure                                    | Surface the error and contact Ground before creating a replacement |

## Wait for readiness

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

Set `FEE_WRAPPER_ID` to the `id` returned by the create response:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
export FEE_WRAPPER_ID="8f4c52d7-62ab-4db9-a964-92f481f6b851"
```

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl \
  "https://sandbox.groundtech.co/v2/fee-wrappers/$FEE_WRAPPER_ID" \
  -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 vault.

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

Update the annual management rate with a separate request containing only
`managementFeeBps`, for example `{"managementFeeBps": 20}`. The rate must be an
integer from 0 through `maxManagementFeeBps` (at most 100). Zero disables management
fees; they can be re-enabled within the original cap. Legacy wrappers with a
zero cap cannot enable management fees. The cap is immutable and is not accepted
as input.

Performance-rate updates remain available while management fees are enabled,
but recipient changes return `409 operation_not_supported`. Send management
updates separately from performance or recipient updates; combined requests
return `400 validation_error`. Each changed request submits one transaction.
The confirmed rate appears in GET/list and `fee_wrapper.fees.status_changed`.
Failed updates do not change stored fees; their webhook includes the requested rate.

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl -X PATCH \
  "https://sandbox.groundtech.co/v2/fee-wrappers/$FEE_WRAPPER_ID/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).