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",
  "name": "Ground USTB gVault"
}

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, follow Manage gtoken access to fetch Ground’s wallet authorization message, collect the address’s signature, and submit the ownershipProof from your backend. The message expires after five minutes. Ground checks your organization’s 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. The calls in steps 4–7 apply to ground_ustb_v1. For tempo_earn_v1, use the Tempo Earn integration guide.

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

The managing organization can remove the address’s deposit access:

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

Poll until allowed becomes false. For ground_ustb_v1, removal blocks future deposits and retains your organization’s management rights; existing shares can still be redeemed. For tempo_earn_v1, removal also blocks share transfers and redemptions until permission is restored.

Getting Started

Integration Guides

Integration Examples

Operations

Resources

API Reference

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