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

# Understanding gVaults and fee wrappers

> Understand the contracts, shares, access controls, and API resources in a gVault integration.

Ground exposes existing RWA vaults as **gVaults**. A gVault accepts a specific
deposit asset, holds or routes into an underlying yield source, and issues
shares representing a proportional claim on the vault.

## The two contract layers

| Layer       | Created by                      | What users hold    | When to use it                                                    |
| ----------- | ------------------------------- | ------------------ | ----------------------------------------------------------------- |
| gVault      | Ground, before your integration | gVault shares      | Direct access without partner revenue sharing                     |
| Fee wrapper | Ground, for your organization   | Fee-wrapper shares | Performance fees or a customer allowlist isolated from the gVault |

The fee wrapper deposits into one existing gVault. It does not create, clone,
or replace that gVault.

## Direct access

In the direct path, your backend calls the gVault allowlist API for the address
that will receive shares. That address can be an EOA, multisig, smart account,
or contract. After authorization confirms, deposits, share accounting, and
redemptions happen onchain against the gVault.

The authorization controls new deposits. Removing it does not confiscate shares
or prevent the holder from exiting an existing position.

## Access through a fee wrapper

In the revenue-sharing path, Ground provisions a fee wrapper over the selected
gVault and authorizes the wrapper against the underlying gVault. Your backend
then manages customer access on the wrapper's own allowlist.

Customers receive fee-wrapper shares. The wrapper owns the underlying gVault
shares, accrues the configured performance fee above its high-water mark, and
mints fee shares to the configured recipient.

## API IDs and contract addresses

Do not interchange these identifiers:

* `gVaultId` identifies an existing gVault in Ground's API.
* The catalogue's `contractAddress` is used for direct onchain calls.
* `id` identifies your organization's wrapper in Ground's API.
* `contractAddress` is the deployed wrapper contract used for onchain calls.
* `requestId` makes fee-wrapper provisioning safely retryable.

## Synchronous and asynchronous operations

Some gVaults expose synchronous ERC-4626-style deposits and withdrawals. Other
gVaults use request/claim methods because settlement depends on an underlying
RWA rail. Use the catalogue's `interface` field to select the correct contract
methods, and document settlement expectations in your application.

A submitted API request, an onchain transaction hash, and final settlement are
different states. Persist the durable IDs for each layer until the operation is
confirmed or claimed.

<CardGroup cols={2}>
  <Card title="Discover gVaults" href="/docs/gvaults/discover-yield-sources">
    Read the catalogue and select the correct interface.
  </Card>

  <Card title="Statuses and events" href="/docs/gvaults/statuses-and-events">
    Map API, transaction, and webhook states.
  </Card>
</CardGroup>