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

# Handle asynchronous gVault operations

> Track API submissions, onchain requests, confirmations, processing, and claims without losing state.

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

| Layer                  | Durable evidence                          | Complete when                                 |
| ---------------------- | ----------------------------------------- | --------------------------------------------- |
| API request            | `requestId` or resource ID                | Ground accepts or rejects the request         |
| Transaction submission | `transactionHash`                         | The transaction confirms successfully         |
| Effective access       | `allowed` from a read endpoint            | The address has the desired effective state   |
| Vault request          | Onchain `requestId` plus transaction hash | The request can be claimed or is terminal     |
| Asset settlement       | Claim receipt and balance change          | Assets or shares reach the intended address   |
| Webhook delivery       | `Ground-Event-Id`                         | Your handler processes the event idempotently |

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](/docs/gvaults/statuses-and-events) for the API and
webhook state vocabulary.