> ## Documentation Index
> Fetch the complete documentation index at: https://docs.groundtech.co/llms.txt
> Use this file to discover all available pages before exploring further.

# Update customer fees

> Updates your fees. Before signing is enabled, changes execute automatically; afterward, your configured signer quorum must approve.

Send any combination of `feeRecipientAddress`, `managementFeeBps` and
`performanceFeeBps`. Omitted fields stay unchanged. Your recipient receives both
management and performance fee shares; Ground's allocation stays unchanged.

Before signing is enabled, fee changes execute automatically. Once enabled,
approve the returned `activityId` with your configured signer quorum through
the portal or [approval API](https://docs.groundtech.co/docs/portfolio-wallets/transaction-approvals.md#approving-an-activity).
Wait for `feeUpdate.status: confirmed` before treating the change as effective. See
[configure fees](https://docs.groundtech.co/docs/gtokens/discover-yield-sources.md#3-configure-your-fees).


## OpenAPI

````yaml swagger/swagger-combined.yaml PATCH /v2/gvaults/{gVaultId}/fees
openapi: 3.0.0
info:
  title: Ground API
  description: Core API for Portfolio Wallets, gtokens, MicroVaults, and webhooks.
  version: 2.0.0
servers:
  - url: https://sandbox.groundtech.co
  - url: https://production.groundtech.co
security:
  - bearerAuth: []
tags:
  - name: System
    description: System health and utility endpoints.
  - name: Sandbox Faucets
    description: Sandbox-only test token faucets.
  - name: Portfolio Wallets
    description: >-
      Portfolio wallets with strategy allocation, deposits, withdrawals, and
      yield positions.
  - name: gVaults
    description: >-
      Direct access to gtokens with deposit access controls and optional fee
      wrappers.
  - name: MicroVaults
    description: >-
      Customer-owned onchain vaults with externally held ERC-20 shares. Private
      preview in sandbox on Ethereum Sepolia.
  - name: Webhook Endpoints
    description: Webhook endpoint management for portfolio wallet notifications.
paths:
  /v2/gvaults/{gVaultId}/fees:
    parameters:
      - name: gVaultId
        in: path
        required: true
        schema:
          $ref: '#/components/schemas/GVaultId'
    patch:
      tags:
        - gVaults
      summary: Update customer fees
      description: >-
        Updates your fees. Before signing is enabled, changes execute
        automatically; afterward, your configured signer quorum must approve.
      operationId: updateGVaultFees
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GVaultFeeRequest'
      responses:
        '200':
          description: Already confirmed.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GVaultFeeMutationStatus'
              example:
                status: confirmed
        '202':
          description: Awaiting processing, customer approval or confirmation.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GVaultFeeMutationStatus'
              example:
                status: awaiting_approval
                activityId: 01a1c873-a53b-7c26-8922-752334ca46d1
        '400':
          description: Invalid address.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          description: >-
            Production gToken access is disabled. Contact Ground admin to enable
            access. Sandbox does not require production enablement.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error: >-
                  Gtoken access is not enabled for your organization. Please
                  contact Ground admin.
                code: product_not_enabled
        '404':
          description: gtoken not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '409':
          description: Conflicting update.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '503':
          $ref: '#/components/responses/ServiceUnavailable'
components:
  schemas:
    GVaultId:
      type: string
      description: >-
        Organization gVault UUID returned by discovery. Existing approved direct
        integrations retain their source slug.
      pattern: >-
        ^(?:[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-4[0-9a-fA-F]{3}-[89aAbB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|ground-ustb-vault|ground-tempo-prime-vault)$
      example: 8f4c52d7-62ab-4db9-a964-92f481f6b851
    GVaultFeeRequest:
      type: object
      description: >-
        Update your management rate, performance rate or fee recipient. Updates
        execute automatically before customer signing is enabled. After
        enablement, the configured customer quorum approves through the existing
        Turnkey endpoints. Ground's fee is already configured; changes initiated
        by Ground follow the same customer signing requirements. Omitted fields
        retain their current values. Only one update may be active per gVault.
      minProperties: 1
      additionalProperties: false
      properties:
        feeRecipientAddress:
          $ref: '#/components/schemas/NonzeroEvmAddress'
          description: >-
            Recipient of your management and performance fee shares. Set a
            recipient distinct from Ground before enabling either customer fee.
            Changing it preserves your rates.
        managementFeeBps:
          type: integer
          minimum: 0
          maximum: 9999
          description: >-
            Your annual management rate. Zero removes only your allocation. Your
            rate plus Ground's rate must fit the deployed ceiling and remain
            below 10000 bps.
        performanceFeeBps:
          type: integer
          minimum: 0
          maximum: 9999
          description: Performance rate within the deployed ceiling.
      example:
        feeRecipientAddress: '0x2222222222222222222222222222222222222222'
        managementFeeBps: 20
        performanceFeeBps: 1500
    GVaultFeeMutationStatus:
      type: object
      additionalProperties: false
      required:
        - status
      properties:
        status:
          type: string
          enum:
            - preparing
            - queued
            - submitting
            - awaiting_approval
            - submitted
            - confirmed
            - failed
          description: '`awaiting_approval` means your approval is required.'
        activityId:
          type: string
          description: >-
            Signing activity for this update. Once signing is enabled, your
            configured signers approve this activity through the portal or
            approval API.
        transactionHash:
          $ref: '#/components/schemas/TransactionHash'
    ErrorResponse:
      type: object
      required:
        - error
        - code
      properties:
        error:
          type: string
          description: >-
            Human-readable error message. May change without notice; do not
            parse programmatically.
        code:
          type: string
          description: >-
            Machine-readable error code. Stable across API versions — safe to
            switch on in client code.
          enum:
            - validation_error
            - unknown_parameters
            - payload_too_large
            - unsupported_media_type
            - submission_id_conflict
            - feedback_unavailable
            - unsupported_chain
            - unsupported_token
            - invalid_destination_address
            - stellar_destination_account_not_active
            - stellar_destination_usdc_not_enabled
            - precision_overflow
            - invalid_cursor
            - unauthenticated
            - forbidden
            - wallet_not_found
            - wallet_limit_reached
            - withdrawal_not_found
            - deposit_not_found
            - yield_source_not_found
            - wallet_projection_unavailable
            - insufficient_funds
            - duplicate_request_id
            - request_id_conflict
            - invalid_position_weight
            - invalid_withdrawal_plan
            - payout_not_found
            - webhook_not_found
            - webhook_duplicate_url
            - withdrawal_not_cancellable
            - withdrawal_already_cancelled
            - withdrawal_payout_in_progress
            - withdrawal_policy_required
            - workflow_conflict
            - stale_rebalance_plan
            - stale_wallet_strategy
            - payout_already_terminal
            - payout_in_progress
            - payout_not_retryable
            - address_book_entry_not_found
            - address_book_duplicate_entry
            - address_book_whitelist_violation
            - rate_limited
            - rate_limit_exceeded
            - internal_error
            - wallet_creation_failed
            - service_temporarily_unavailable
            - operation_not_supported
            - wallet_withdrawal_active
            - stellar_customer_approval_unavailable
            - withdrawal_signing_required
            - wallet_performance_unavailable
            - tempo_beta_transfer_limit_exceeded
            - product_not_enabled
    NonzeroEvmAddress:
      type: string
      description: >-
        Valid nonzero EVM EOA or contract address. Mixed-case values must use a
        valid EIP-55 checksum.
      minLength: 42
      maxLength: 42
      pattern: ^0x(?!0{40}$)[0-9a-fA-F]{40}$
      example: '0x3bf25a73a1f1033c2d50ac65f3c9d6a44123db81'
    TransactionHash:
      type: string
      description: EVM transaction hash.
      minLength: 66
      maxLength: 66
      pattern: ^0x[0-9a-fA-F]{64}$
      example: '0xabababababababababababababababababababababababababababababababab'
    AuthErrorResponse:
      type: object
      required:
        - error
      properties:
        error:
          type: string
          description: Authentication or authorization error message.
        message:
          type: string
          nullable: true
          description: Additional auth middleware detail, when present.
        code:
          type: string
          nullable: true
          enum:
            - unauthenticated
            - forbidden
          description: >-
            Some auth and scope failures include a stable code; middleware
            errors may omit it.
    ServiceUnavailableError:
      allOf:
        - $ref: '#/components/schemas/ErrorResponse'
        - type: object
          properties:
            retryable:
              type: boolean
              description: Whether the client should retry with the same requestId
  responses:
    Unauthorized:
      description: >-
        The request is missing a valid bearer token, or the token is invalid or
        expired.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/AuthErrorResponse'
          example:
            error: Unauthenticated request
            message: Missing or invalid bearer token
    ServiceUnavailable:
      description: >-
        An upstream dependency is temporarily unavailable. The request can be
        retried with the same `requestId`.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ServiceUnavailableError'
          example:
            error: Service temporarily unavailable
            code: service_temporarily_unavailable
            retryable: true
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.