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

# gtoken quickstart

> Discover a sandbox gtoken source, authorize an address, and deposit into its backing vault.

This quickstart follows the direct integration path. Your backend uses Ground's
API to discover a gtoken source and authorize an address. The user then approves
the deposit asset and deposits into the backing vault onchain to receive gtokens.

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

<span id="1-discover-a-gvault" />

## 1. Discover a gtoken source

The gtoken API uses the `/v2/gvaults` namespace. Use the returned source ID as
`gVaultId`.

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

Set `GVAULT_ID` to the selected row's `id`:

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

See [Discover gtoken yield sources](/docs/gtokens/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/$GVAULT_ID/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/$GVAULT_ID/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 vault
interface; not every backing vault 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 backing vault, 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. A successful synchronous
deposit sends gtokens to that address. For a Centrifuge-style backing vault,
deposits use a request/claim lifecycle instead. Follow
[Deposit and redeem onchain](/docs/gtokens/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/gtokens/integrate-directly-onchain">
    Build the complete direct access flow.
  </Card>

  <Card title="Configure revenue sharing" href="/docs/gtokens/configure-revenue-sharing">
    Have Ground provision a fee wrapper over the selected gtoken's backing vault.
  </Card>
</CardGroup>