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

# Configure revenue sharing on gVaults

> Have Ground provision a fee wrapper and integrate its customer and fee lifecycle.

Ground can provision a fee wrapper around an existing gVault. The wrapper
holds the underlying gVault position, issues its own shares to your users, and
accrues a performance fee above its high-water mark.

## 1. Create a server-side API key

Create an API key in the
[Ground Developer Portal](https://portal.groundtech.co) and keep it on your
backend.

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
export GROUND_API_KEY="<your-api-key>"
```

## 2. Select the underlying gVault

Call `GET /v2/gvaults/yield-sources` and select the underlying gVault. Pass that
row's `id` as `gVaultId` when provisioning the fee wrapper.

## 3. Provision the fee wrapper

Generate a UUID v4 for `requestId`, then submit:

```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": "a1b2c3d4-0000-4000-8000-000000000001",
    "gVaultId": "ground-ustb-vault",
    "feeRecipientAddress": "0x3333333333333333333333333333333333333333",
    "performanceFeeBps": 2000
  }'
```

`performanceFeeBps` is expressed in basis points. `2000` means that 20% of
gains above the wrapper's high-water mark accrue to `feeRecipientAddress`.
Management fees are not configured by this endpoint.

The initial performance-fee rate becomes the wrapper's permanent maximum. A
wrapper created with `performanceFeeBps: 0` cannot enable a performance fee
later.

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

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "id": "abababab-abab-4bab-8bab-abababababab",
  "requestId": "a1b2c3d4-0000-4000-8000-000000000001",
  "gVaultId": "ground-ustb-vault",
  "status": "provisioning",
  "contractAddress": null,
  "feeRecipientAddress": "0x3333333333333333333333333333333333333333",
  "performanceFeeBps": 2000,
  "maxPerformanceFeeBps": 2000
}
```

## 4. Wait for onchain readiness

Poll the returned resource:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl \
  https://sandbox.groundtech.co/v2/fee-wrappers/abababab-abab-4bab-8bab-abababababab \
  -H "Authorization: Bearer $GROUND_API_KEY"
```

Wait for `status: ready`. Store `id` for future API calls and
`contractAddress` for onchain transactions. Ground provisions the wrapper and
authorizes it to use the selected underlying gVault before reporting it ready.

You can also recover a wrapper by its provisioning request:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl \
  "https://sandbox.groundtech.co/v2/fee-wrappers?requestId=a1b2c3d4-0000-4000-8000-000000000001" \
  -H "Authorization: Bearer $GROUND_API_KEY"
```

## 5. Allowlist each customer

Before a customer's first deposit, call:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl -X PUT \
  https://sandbox.groundtech.co/v2/fee-wrappers/abababab-abab-4bab-8bab-abababababab/allowlist/0x2222222222222222222222222222222222222222 \
  -H "Authorization: Bearer $GROUND_API_KEY"
```

Poll the corresponding `GET` endpoint until it returns `allowed: true`. This
allowlist belongs to the fee wrapper and is separate from the underlying
gVault's address allowlist.

## 6. Integrate deposits

Read `asset()` from `contractAddress`, approve that token for the wrapper, and
call:

```solidity theme={"theme":{"light":"github-light","dark":"github-dark"}}
deposit(uint256 assets, address receiver)
```

Set `receiver` to the allowlisted customer address. The customer receives fee
wrapper shares, not shares in the underlying gVault.

Useful read methods include:

```solidity theme={"theme":{"light":"github-light","dark":"github-dark"}}
asset() external view returns (address);
previewDeposit(uint256 assets) external view returns (uint256 shares);
convertToAssets(uint256 shares) external view returns (uint256 assets);
totalAssets() external view returns (uint256 assets);
```

## 7. Integrate withdrawals

For an immediate exit, read `maxWithdraw(owner)` or `maxRedeem(owner)`, then
call:

```solidity theme={"theme":{"light":"github-light","dark":"github-dark"}}
withdraw(uint256 assets, address receiver, address owner)
redeem(uint256 shares, address receiver, address owner)
```

For a larger exit, use:

```solidity theme={"theme":{"light":"github-light","dark":"github-dark"}}
requestRedeem(address owner, uint256 shares)
claimRedeem(address owner, uint256 requestId)
```

The wrapper translates its share amount into underlying gVault shares and
manages the underlying queued redemption. Persist the returned `requestId`
until the claim confirms.

## 8. Update revenue sharing

You can change the fee recipient, reduce the fee, or restore it up to the
creation-time maximum:

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

Omit either field to leave it unchanged. The wrapper accrues fees under the old
configuration before applying the update. A rate above
`maxPerformanceFeeBps` is rejected.

## 9. Remove customer deposit access

Call `DELETE /v2/fee-wrappers/{id}/allowlist/{address}`. Removal blocks new deposits but preserves
the customer's ability to exit an existing position.