gtoken quickstart

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.

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

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

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:

export GVAULT_ID="ground-ustb-vault"

See Discover gtoken yield sources for the complete response contract.

2. Authorize the address

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:

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.

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:

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

Direct integration guide

Build the complete direct access flow.

Configure revenue sharing

Have Ground provision a fee wrapper over the selected gtoken’s backing vault.

Getting Started

Integration Guides

Operations

Resources

gtoken quickstart

Prerequisites

1. Discover a gtoken source

2. Authorize the address

3. Read the contract configuration

4. Submit the deposit

5. Record the result

Direct integration guide

Configure revenue sharing

​Prerequisites

​1. Discover a gtoken source

​2. Authorize the address

​3. Read the contract configuration

​4. Submit the deposit

​5. Record the result

Direct integration guide

Configure revenue sharing

Prerequisites

1. Discover a gtoken source

2. Authorize the address

3. Read the contract configuration

4. Submit the deposit

5. Record the result