Skip to main content
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.