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

# Manage gtoken access

> Authorize, verify, and remove an address for direct deposits into a gtoken backing vault.

The gtoken allowlist permits deposits into the token's backing vault. The subject
is an EVM `address`, not necessarily a wallet: it can be an EOA, multisig, smart
account, or another contract.

## Add an address

Call from your backend with the `id` returned by the gtoken catalogue:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
export GVAULT_ID="ground-ustb-vault"
export CUSTOMER_ADDRESS="0x3bf25a73a1f1033c2d50ac65f3c9d6a44123db81"
```

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl -X PUT \
  "https://sandbox.groundtech.co/v2/gvaults/$GVAULT_ID/allowlist/$CUSTOMER_ADDRESS" \
  -H "Authorization: Bearer $GROUND_API_KEY"
```

The operation is idempotent for the desired allowlisted state:

* `200` with `status: confirmed` means no further state change is pending.
* `202` with `status: submitted` and `transactionHash` means Ground broadcast
  the update, but it has not necessarily confirmed.

## Verify the effective state

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl \
  "https://sandbox.groundtech.co/v2/gvaults/$GVAULT_ID/allowlist/$CUSTOMER_ADDRESS" \
  -H "Authorization: Bearer $GROUND_API_KEY"
```

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "allowed": true
}
```

Do not enable deposits until `allowed` is `true`. A transaction hash proves
submission, not confirmation or effective authorization.

## Remove an address

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl -X DELETE \
  "https://sandbox.groundtech.co/v2/gvaults/$GVAULT_ID/allowlist/$CUSTOMER_ADDRESS" \
  -H "Authorization: Bearer $GROUND_API_KEY"
```

Removing your organization's grant blocks future deposits after the effective
allowlist state becomes false. It does not seize shares or block redemption of
an existing position. If another authorized organization still grants access,
the effective state may remain true.

## Handle failures

Treat `404` as an unknown gtoken source or unavailable organization resource, `409` as
a conflicting in-flight state change, and `503` as a temporary submission
failure. Before retrying an uncertain request, read the effective state.

API reference:
[add](/api-reference/add-gtoken-allowlist),
[get](/api-reference/get-gtoken-allowlist), and
[remove](/api-reference/delete-gtoken-allowlist).