Understanding gtokens and fee wrappers

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

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.