Skip to main content
Ground can provision a fee wrapper around an existing gVault. The wrapper holds the underlying gVault position, 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 underlying gVault

Call GET /v2/gvaults/yield-sources and select the underlying gVault. 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. Management fees are not configured by this endpoint. 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

Poll the returned 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 underlying gVault 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 gVault’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, not shares in the underlying gVault. 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 gVault shares 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.