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

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

A **gtoken** is the receipt token a user receives by depositing a supported
asset into a Ground vault contract. Each backing vault holds or routes assets
into an underlying RWA yield source and issues gtokens representing a
proportional claim on that vault.

## The two contract layers

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

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

## Direct access

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

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
gtoken's backing vault and authorizes the wrapper against that vault. Your backend
then manages customer access on the wrapper's own allowlist.

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

## API IDs and contract addresses

The gtoken API uses the `/v2/gvaults` namespace. Use the returned source ID as
`gVaultId`. Do not interchange these identifiers:

* `gVaultId` identifies a gtoken yield source 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 backing vaults expose synchronous ERC-4626-style deposits and withdrawals. Other
vaults 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 gtokens" href="/docs/gtokens/discover-yield-sources">
    Read the catalogue and select the correct interface.
  </Card>

  <Card title="Webhooks" href="/docs/gtokens/webhooks">
    Receive status-change events and reconcile asynchronous updates.
  </Card>
</CardGroup>