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

# Integrating directly onchain with Ground's gVaults

> Discover a Ground gVault, authorize an EVM address, and integrate deposits and withdrawals.

In a direct integration, users interact with an existing Ground gVault and
receive its shares 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](https://portal.groundtech.co). Store it only on your
backend.

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
export GROUND_API_KEY="<your-api-key>"
```

Never expose this key in a browser or mobile client.

## 2. Discover available gVaults

Retrieve the environment's yield-source catalogue:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
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.

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "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.

## 3. Allowlist the user's address

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

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl -X PUT \
  https://sandbox.groundtech.co/v2/gvaults/ground-ustb-vault/allowlist/0x2222222222222222222222222222222222222222 \
  -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:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl \
  "https://sandbox.groundtech.co/v2/gvaults/ground-ustb-vault/allowlist/0x2222222222222222222222222222222222222222" \
  -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 gVault contract:

```solidity theme={"theme":{"light":"github-light","dark":"github-dark"}}
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 gVault contract to spend the deposit asset:

```solidity theme={"theme":{"light":"github-light","dark":"github-dark"}}
IERC20(asset).approve(gVaultAddress, assets);
```

Then the user deposits:

```solidity theme={"theme":{"light":"github-light","dark":"github-dark"}}
deposit(uint256 assets, address receiver)
```

Set `receiver` to the allowlisted address that should receive the gVault shares.
The gVault checks the receiver's access, not merely the transaction sender.

Before submitting, you can estimate the output with:

```solidity theme={"theme":{"light":"github-light","dark":"github-dark"}}
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:

```solidity theme={"theme":{"light":"github-light","dark":"github-dark"}}
maxWithdraw(address owner) external view returns (uint256 assets);
maxRedeem(address owner) external view returns (uint256 shares);
```

Within that capacity, the share owner can call:

```solidity theme={"theme":{"light":"github-light","dark":"github-dark"}}
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:

```solidity theme={"theme":{"light":"github-light","dark":"github-dark"}}
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:

```solidity theme={"theme":{"light":"github-light","dark":"github-dark"}}
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:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl -X DELETE \
  "https://sandbox.groundtech.co/v2/gvaults/ground-ustb-vault/allowlist/0x2222222222222222222222222222222222222222" \
  -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.