Skip to main content
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.
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.
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:
See Discover gtoken yield sources for the complete response contract.

​
2. Authorize the address

Follow Manage gtoken access to fetch the wallet authorization message, have the address sign it, and submit its ownershipProof from your backend. Ground checks your source access and screens the address before admission. A 202 response means processing is pending. Poll the allowlist endpoint and enable deposits only after allowed is true and processing is complete.

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

​
4. Submit the deposit

For a synchronous USTB-style backing vault, approve the exact asset amount and call:
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.