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

# gVault Quickstart

> Discover a sandbox gVault, authorize an address, and prepare the first onchain deposit.

This quickstart follows the direct integration path. Your backend uses Ground's
API to discover the gVault and authorize an address. The user then approves the
deposit asset and interacts with the gVault onchain.

## Prerequisites

You need a Ground sandbox API key, an EVM address controlled by your user or
application, and enough of the listed deposit token and native gas token to
submit sandbox transactions.

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
export GROUND_API_KEY="<sandbox-api-key>"
export CUSTOMER_ADDRESS="0x2222222222222222222222222222222222222222"
```

Keep the Ground API key on your server. Never place it in frontend code.

## 1. Discover a gVault

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

Select a row and persist its `id`, `contractAddress`, `asset`, and `interface`.
Resolve these values independently in sandbox and production.

See [Discover gVault yield sources](/docs/gvaults/discover-yield-sources) for
the complete response contract.

## 2. Authorize the address

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

A `200` response is already confirmed. A `202` response means the authorization
transaction was submitted. In that case, poll the allowlist state until
`allowed` is `true`:

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

## 3. Read the contract configuration

At the returned `contractAddress`, call `asset()` to resolve the ERC-20 deposit
token. Treat the catalogue's `interface` as the selector for the correct gVault
interface; not every gVault has the same synchronous or asynchronous methods.

```solidity theme={"theme":{"light":"github-light","dark":"github-dark"}}
address depositAsset = gVault.asset();
uint8 shareDecimals = gVault.decimals();
```

## 4. Submit the deposit

For a synchronous USTB-style gVault, approve the exact asset amount and call:

```solidity theme={"theme":{"light":"github-light","dark":"github-dark"}}
IERC20(depositAsset).approve(gVaultAddress, assets);
uint256 shares = gVault.deposit(assets, customerAddress);
```

Set the deposit receiver to the authorized address. For a Centrifuge-style
gVault, deposits use a request/claim lifecycle instead. Follow
[Deposit and redeem onchain](/docs/gvaults/deposit-and-redeem) for the interface
returned by the selected yield source.

## 5. Record the result

Store the environment, `gVaultId`, contract address, chain ID, transaction hash,
asset amount, share amount, and receiving address. Treat the transaction as
complete only after the required chain confirmations.

<CardGroup cols={2}>
  <Card title="Direct integration guide" href="/docs/gvaults/integrate-directly-onchain">
    Build the complete direct access flow.
  </Card>

  <Card title="Configure revenue sharing" href="/docs/gvaults/configure-revenue-sharing">
    Have Ground provision a fee wrapper over the selected gVault.
  </Card>
</CardGroup>