> ## 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.

# Test a gVault integration in sandbox

> Validate discovery, access, contract calls, asynchronous operations, and webhooks before production.

Use `https://sandbox.groundtech.co` for API calls and the chain returned by the
sandbox gVault catalogue for transactions. Sandbox and production are separate
environments with separate IDs, contract addresses, API keys, and webhook
registrations.

## Build an environment manifest

At application startup, call `GET /v2/gvaults/yield-sources` and record:

* API base URL and environment
* `gVaultId`, `interface`, chain, and `contractAddress`
* asset contract address, symbol, decimals, and chain ID

Fail closed if the configured chain or contract does not match the manifest.

## Test the direct path

1. Add a fresh test address to the selected gVault allowlist.
2. Wait for the effective state to become `allowed: true`.
3. Approve and deposit the smallest supported test amount.
4. Confirm the share balance at the intended receiver.
5. Exercise a synchronous withdrawal when available.
6. Exercise request/claim redemption when supported.
7. Remove access and verify a new deposit is blocked while exit remains possible.

## Test the fee-wrapper path

1. Provision a wrapper with a new UUID v4 and nonzero test fee.
2. Retry the identical create request to validate idempotency.
3. Recover the wrapper by `requestId` and wait for `ready`.
4. Add a customer address to the wrapper allowlist.
5. Deposit and confirm that the customer receives wrapper shares, not gVault shares.
6. Reduce the performance fee and change its recipient.
7. Remove customer access and verify the existing position can still exit.

## Test failure handling

Exercise invalid addresses, unknown IDs, conflicting `requestId` payloads,
unconfirmed access, wrong-chain transactions, insufficient balances, and
temporary `429` or `503` responses. Retries should reconcile current state
before resubmission.

## Test webhooks

Register a sandbox-only HTTPS endpoint, preserve the one-time secret, verify
signatures from the raw body, deduplicate by `Ground-Event-Id`, and compare your
processed events with `GET /v2/gvaults/webhooks/events`.

Before production, fetch a fresh production catalogue and repeat the manifest
checks. Never promote sandbox contract addresses or webhook secrets.