Skip to main content
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:

​
Provision a wrapper

Select a gVaultId from the gtoken catalogue and generate a UUID v4:
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.

​
gUSTB wrapper shares

The gUSTB fee wrapper issues 18-decimal shares. The first depositor receives all shares minted for their deposit; no seed shares are permanently locked. Share conversions include virtual units to reduce the effect of donation-based rounding attacks. These units exist only in pricing and never appear in your balance. Read previewDeposit or previewRedeem from the wrapper to estimate the result and record the actual shares or assets returned by the transaction. Rounding can leave small residual assets, and donations can change quotes. Use the router’s minimum-share limit for routed deposits. New gUSTB wrapper deposits require current authorization from the backing vault. If Ground revokes that authorization, deposits revert and maxDeposit returns zero. Existing holdings can still be redeemed and pending redemptions claimed, subject to the usual freeze and liquidity restrictions. Revocation retains the wrapper’s pooled-asset recovery protection.

​
Provisioning statuses

​
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:
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:

​
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.
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, list, get, and update fees.