Configure revenue sharing on gtokens

Have Ground provision a fee wrapper and integrate its customer and fee lifecycle.

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.

export GROUND_API_KEY="<your-api-key>"

​

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.

export GVAULT_ID="ground-ustb-vault"

​

3. Provision the fee wrapper

Generate a UUID v4 for requestId, then submit:

curl -X POST https://sandbox.groundtech.co/v2/fee-wrappers \
  -H "Authorization: Bearer $GROUND_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "requestId": "a1b2c3d4-0000-4000-8000-000000000001",
    "gVaultId": "'$GVAULT_ID'",
    "feeRecipientAddress": "0x3333333333333333333333333333333333333333",
    "performanceFeeBps": 2000
  }'

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, with a default of zero. Ground sets the permanent management-fee cap to 100 bps; you cannot supply that cap. Both fees use the same recipient. 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.

{
  "id": "abababab-abab-4bab-8bab-abababababab",
  "requestId": "a1b2c3d4-0000-4000-8000-000000000001",
  "gVaultId": "ground-ustb-vault",
  "status": "provisioning",
  "contractAddress": null,
  "feeRecipientAddress": "0x3333333333333333333333333333333333333333",
  "performanceFeeBps": 2000,
  "maxPerformanceFeeBps": 2000,
  "managementFeeBps": 0,
  "maxManagementFeeBps": 100,
  "createdAt": "2026-10-19T12:00:00.000Z",
  "updatedAt": "2026-10-19T12:00:00.000Z"
}

​

4. Wait for onchain readiness

Set FEE_WRAPPER_ID to the id returned by the create response, then poll that resource:

export FEE_WRAPPER_ID="abababab-abab-4bab-8bab-abababababab"

curl \
  "https://sandbox.groundtech.co/v2/fee-wrappers/$FEE_WRAPPER_ID" \
  -H "Authorization: Bearer $GROUND_API_KEY"

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:

curl \
  "https://sandbox.groundtech.co/v2/fee-wrappers?requestId=a1b2c3d4-0000-4000-8000-000000000001" \
  -H "Authorization: Bearer $GROUND_API_KEY"

​

5. Allowlist each customer

Before a customer’s first deposit, call:

curl -X PUT \
  "https://sandbox.groundtech.co/v2/fee-wrappers/$FEE_WRAPPER_ID/allowlist/0x2222222222222222222222222222222222222222" \
  -H "Authorization: Bearer $GROUND_API_KEY"

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:

deposit(uint256 assets, address receiver)

Set receiver to the allowlisted customer address. The customer receives fee wrapper shares, while the wrapper holds the underlying gtokens.

Useful read methods include:

asset() external view returns (address);
previewDeposit(uint256 assets) external view returns (uint256 shares);
convertToAssets(uint256 shares) external view returns (uint256 assets);
totalAssets() external view returns (uint256 assets);

​

7. Integrate withdrawals

For an immediate exit, read maxWithdraw(owner) or maxRedeem(owner), then call:

withdraw(uint256 assets, address receiver, address owner)
redeem(uint256 shares, address receiver, address owner)

For a larger exit, use:

requestRedeem(address owner, uint256 shares)
claimRedeem(address owner, uint256 requestId)

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

When management fees are disabled, you can change the fee recipient. You can reduce the performance fee or restore it up to the creation-time maximum:

curl -X PATCH \
  "https://sandbox.groundtech.co/v2/fee-wrappers/$FEE_WRAPPER_ID/fees" \
  -H "Authorization: Bearer $GROUND_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "feeRecipientAddress": "0x4444444444444444444444444444444444444444",
    "performanceFeeBps": 1500
  }'

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.

To update the annual management-fee 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.

See Manage fee wrappers for the full fee configuration.

​

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.