Skip to main content
gVault integrations have two independent asynchronous boundaries: Ground API mutations that submit onchain administration transactions, and vault operations whose underlying RWA settlement completes later.

​
Keep the state layers separate

A 202 response or transaction hash is not final confirmation. A confirmed request transaction is not the same as completed RWA settlement.

​
Fee-wrapper provisioning

Generate one UUID v4 per logical wrapper and persist it before the POST. If the request outcome is uncertain, retry the same payload with the same requestId or query GET /v2/fee-wrappers?requestId=.... Never create a new ID merely because the client timed out. Treat provisioning as pending, ready as usable, and failed as terminal for that request. Do not use contractAddress until readiness is confirmed.

​
Access and fee updates

When an allowlist or fee mutation returns submitted, retain its transaction hash and poll the associated read endpoint or consume the status-change webhook. Before retrying after a timeout, read the current resource to avoid submitting a duplicate or contradictory change.

​
Onchain request/claim flows

Persist the contract address, chain ID, owner, transaction hash, returned onchain request ID, requested amount, and minimum-output parameters. Use onchain state or a successful call simulation to determine whether a claim is ready. Elapsed time from processingPolicies is an estimate, not proof of claimability. For a claim, reconcile all three facts:
  1. The claim transaction succeeded.
  2. The expected assets or shares moved to the intended address.
  3. Your local operation record is marked terminal exactly once.
See Statuses and event types for the API and webhook state vocabulary.