Skip to main content
Use https://sandbox.groundtech.co for API calls and the chain returned by the sandbox gtoken catalogue for transactions. Sandbox and production are separate environments with separate contract addresses, API keys, and webhook registrations. Public gtoken IDs can be shared across environments; always resolve their contracts from the catalogue for the selected API base URL. Tempo’s Moderato sandbox uses mock USDC.e and PRIME with a manually updated oracle.

​
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 gtoken allowlist.
  2. Wait for the effective state to become allowed: true.
  3. Approve and deposit the smallest supported test amount.
  4. Confirm the gtoken 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. For ground_ustb_v1, exit remains possible; for tempo_earn_v1, share transfers and redemption are also blocked until access is restored.

​
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, while the wrapper holds the underlying gtokens.
  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.