> ## 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 gtoken operations

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

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

## Mutation statuses

| Status      | Meaning                                                                               |
| ----------- | ------------------------------------------------------------------------------------- |
| `submitted` | Ground broadcast an onchain transaction, but its requested state is not yet confirmed |
| `confirmed` | The requested state is effective onchain                                              |
| `failed`    | The transaction or resulting state change reached a terminal failure                  |

Do not infer `confirmed` from elapsed time. Read the resource, verify the
transaction receipt and resulting onchain state, or process the confirming
webhook.

## 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 [Integrate gtoken webhooks](/docs/gtokens/webhooks) for event payloads and
delivery statuses.