Integrate gtokens directly onchain

In a direct integration, users deposit into an existing Ground vault and receive gtokens in their existing wallets. Ground does not deploy a fee wrapper for this path.

1. Create a server-side API key

Create an API key in the Ground Developer Portal. Store it only on your backend.

export GROUND_API_KEY="<your-api-key>"

Never expose this key in a browser or mobile client.

2. Discover available gtokens

Retrieve the environment’s yield-source catalogue:

curl https://sandbox.groundtech.co/v2/gvaults/yield-sources \
  -H "Authorization: Bearer $GROUND_API_KEY"

Each returned row is an integration manifest. Its id is the gVaultId used by the allowlist API, while contractAddress is the contract your application calls onchain.

{
  "id": "ground-ustb-vault",
  "chain": "ethereum_sepolia",
  "contractAddress": "0x1111111111111111111111111111111111111111",
  "asset": {
    "symbol": "USDC",
    "contractAddress": "0x2222222222222222222222222222222222222222",
    "decimals": 6
  },
  "interface": "ground_ustb_v1"
}

Do not copy production addresses into sandbox configuration. Resolve the catalogue separately in each environment. Set GVAULT_ID from the selected catalogue row and CUSTOMER_ADDRESS to the address that will receive gtokens:

export GVAULT_ID="ground-ustb-vault"
export CUSTOMER_ADDRESS="0x2222222222222222222222222222222222222222"

3. Allowlist the user’s address

Before the user’s first deposit, call the allowlist endpoint from your backend:

curl -X PUT \
  "https://sandbox.groundtech.co/v2/gvaults/$GVAULT_ID/allowlist/$CUSTOMER_ADDRESS" \
  -H "Authorization: Bearer $GROUND_API_KEY"

The address can be an EOA, multisig, or contract. A 200 response means the desired state is already confirmed. A 202 response means Ground submitted an onchain allowlist transaction. Poll until confirmed:

curl \
  "https://sandbox.groundtech.co/v2/gvaults/$GVAULT_ID/allowlist/$CUSTOMER_ADDRESS" \
  -H "Authorization: Bearer $GROUND_API_KEY"

Enable deposits only after the response contains "allowed": true.

4. Read the deposit asset

Read the ERC-4626-style asset() method from the backing vault contract:

function asset() external view returns (address);

Use the returned token address for the user’s approval and express assets in that token’s native units.

5. Approve and deposit

The user first approves the backing vault contract to spend the deposit asset:

IERC20(asset).approve(gVaultAddress, assets);

Then the user deposits:

deposit(uint256 assets, address receiver)

Set receiver to the allowlisted address that should receive gtokens. The backing vault checks the receiver’s access, not merely the transaction sender. Before submitting, you can estimate the output with:

previewDeposit(uint256 assets) external view returns (uint256 shares);
maxDeposit(address receiver) external view returns (uint256 assets);

6. Withdraw within current liquidity

Read the user’s immediately available capacity:

maxWithdraw(address owner) external view returns (uint256 assets);
maxRedeem(address owner) external view returns (uint256 shares);

Within that capacity, the share owner can call:

withdraw(uint256 assets, address receiver, address owner)
redeem(uint256 shares, address receiver, address owner)

For a direct wallet transaction, set owner to the calling wallet. receiver is the address that receives the deposit asset.

7. Request a larger redemption

When the requested exit exceeds current synchronous liquidity, submit an asynchronous redemption:

requestRedeem(address owner, uint256 shares)

The transaction returns a requestId. Ground processes queued redemptions onchain. After the request is processed, the same owner claims the proceeds:

claimRedeem(address owner, uint256 requestId)

Keep the original transaction hash and returned requestId in your operation record until the claim confirms.

8. Remove deposit access

To remove your organization’s grant:

curl -X DELETE \
  "https://sandbox.groundtech.co/v2/gvaults/$GVAULT_ID/allowlist/$CUSTOMER_ADDRESS" \
  -H "Authorization: Bearer $GROUND_API_KEY"

Removing access blocks future deposits after the final organization grant is removed. It does not block the address from withdrawing an existing position.

Getting Started

Integration Guides

Operations

Resources

Integrate gtokens directly onchain

1. Create a server-side API key

2. Discover available gtokens

3. Allowlist the user’s address

4. Read the deposit asset

5. Approve and deposit

6. Withdraw within current liquidity

7. Request a larger redemption

8. Remove deposit access

​1. Create a server-side API key

​2. Discover available gtokens

​3. Allowlist the user’s address

​4. Read the deposit asset

​5. Approve and deposit

​6. Withdraw within current liquidity

​7. Request a larger redemption

​8. Remove deposit access

1. Create a server-side API key

2. Discover available gtokens

3. Allowlist the user’s address

4. Read the deposit asset

5. Approve and deposit

6. Withdraw within current liquidity

7. Request a larger redemption

8. Remove deposit access