Skip to main content
Ground can provision a fee wrapper around a gtoken’s existing backing vault. The wrapper holds the underlying gtokens, 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 and keep it on your backend.

​
2. Select the gtoken source

Call GET /v2/gvaults/yield-sources and select the gtoken yield source. 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:
performanceFeeBps is expressed in basis points. 2000 means that 20% of gains above the wrapper’s high-water mark accrue to feeRecipientAddress. To also charge an annual management fee, include managementFeeBps in the request. For example, 10 means 0.10% annually; the supported range is 0 through 100 bps. See Manage fee wrappers for fee caps and update rules. 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.

​
4. Wait for onchain readiness

Set FEE_WRAPPER_ID to the id returned by the create response, then poll that resource:
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 backing vault before reporting it ready. You can also recover a wrapper by its provisioning request:

​
5. Allowlist each customer

Before a customer’s first deposit, call:
Poll the corresponding GET endpoint until it returns allowed: true. This allowlist belongs to the fee wrapper and is separate from the underlying vault’s address allowlist.

​
6. Integrate deposits

Read asset() from contractAddress, approve that token for the wrapper, and call:
Set receiver to the allowlisted customer address. The customer receives fee wrapper shares, while the wrapper holds the underlying gtokens. Useful read methods include:

​
7. Integrate withdrawals

For an immediate exit, read maxWithdraw(owner) or maxRedeem(owner), then call:
For a larger exit, use:
The wrapper translates its share amount into underlying gtokens 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:
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. For annual management fees, add managementFeeBps (0–100, default 0) when creating the wrapper. Ground fixes the cap at 100 bps; it is not a request parameter. Management fees use the same recipient as performance fees. To update the annual rate, PATCH the fees endpoint with only managementFeeBps, within the original cap. Zero disables management fees. Performance updates use a separate request; recipient changes remain unavailable while management fees are enabled.