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

# Tempo Earn vaults

> Discover a vault, authorize your user’s wallet, and deposit and redeem directly on Tempo.

Use Tempo’s or Ground’s API to discover the vault, Ground’s API to authorize
wallet access, and the user’s wallet to submit deposits and redemptions onchain.
Your users receive vault shares; they do not need to interact with the underlying
pool or hold PRIME themselves.

## 1. Discover the vault

If you already use the [Tempo Earn API](https://tempo.xyz/developers/docs/api/earn),
select the Ground vault from the vaults available in your environment and retain
its address and network.

Alternatively, use Ground’s
[List gtoken yield sources](/api-reference/list-gtoken-yield-sources) endpoint:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl https://sandbox.groundtech.co/v2/gvaults/yield-sources \
  -H "Authorization: Bearer $GROUND_API_KEY"
```

Use `https://production.groundtech.co` for mainnet. Create your API key in the
[Ground Developer Portal](https://portal.groundtech.co) and keep it on your
backend. Your organization must have access to the selected source.

Select a row with `interface: tempo_earn_v1`. If you discovered the vault through
Tempo, match its address and network to this Ground catalogue row to obtain the
`id` required for Ground’s access API.

Keep the following fields for the selected environment:

| Field | Use |
| - | - |
| `id` | `gVaultId` for Ground’s wallet-access requests |
| `chain` | Network for wallet connections and transactions |
| `contractAddress` | Vault address for deposits and redemptions |
| `asset.contractAddress`, `asset.decimals` | Deposit token and amount precision |
| `shareTokenAddress` | Separate TIP-20 token representing the user’s vault shares |

Read `asset()` and `earnShare()` from the vault and confirm they match the
catalogue before requesting token approvals.

## 2. Authorize the user’s wallet

Use the address that will hold the shares. Your backend calls Ground with its
API key; the user signs the authorization with that wallet:

1. Fetch `GET /v2/gvaults/{gVaultId}/allowlist/{address}/authorization`.
2. Ask the wallet to sign the returned typed data. This proves wallet ownership;
   it is not a deposit transaction.
3. Submit `PUT /v2/gvaults/{gVaultId}/allowlist/{address}` with the signed
   `ownershipProof`.
4. Poll `GET /v2/gvaults/{gVaultId}/allowlist/{address}` until `allowed` is `true`
   and `status` is `confirmed` before enabling deposits. A `202` response means
   admission is still processing.

The authorization expires after five minutes. See
[Manage gtoken access](/docs/gtokens/manage-gtoken-access) for the request bodies,
signing example, and error handling. Discovery through Tempo does not grant
wallet access.

## 3. Deposit and receive shares

We recommend [Viem’s Tempo actions](https://viem.sh/tempo) to read positions and
submit transactions. Its Earn helpers handle token approvals for deposits and
redemptions. Use a version compatible with the deployed vault ABI; the direct
contract calls below also work with your preferred EVM client.

Choose the deposit amount in the asset’s native units. For a six-decimal token,
`1_000_000` units is one token. Quote or simulate the deposit and set a minimum
acceptable share output; share units are not interchangeable with asset units.

From the user’s wallet:

1. Approve the **deposit token** for the **vault address** to spend the amount.
2. Call `deposit(uint256 assets, address receiver, uint256 minEarnShares)`, with
   the authorized wallet as `receiver`.
3. Wait for a successful receipt and read the wallet’s share balance.

[Viem’s `earn.deposit`](https://viem.sh/tempo/actions/earn.deposit) provides the
SDK equivalent. The deposit settles synchronously: it succeeds with shares
issued or reverts. There is no separate claim step.

## 4. Display the position

Read `balanceOf(address)` on the **share token**, not the vault, to obtain the
user’s shares. [Viem’s `earn.getPosition`](https://viem.sh/tempo/actions/earn.getPosition)
returns the share balance and its current value in the deposit asset.

Display the share balance and asset value separately. Refresh after confirmed
transactions and when showing a redemption quote; a displayed valuation does
not reserve liquidity or guarantee an execution price.

## 5. Redeem shares for the deposit token

Obtain a current quote with `previewRedeem(uint256 earnShares)` or
[Viem’s `earn.getRedeemQuote`](https://viem.sh/tempo/actions/earn.getRedeemQuote).
Apply your chosen tolerance to set the minimum acceptable asset output.

From the share owner’s wallet:

1. Approve the **share token** for the **vault address** to spend the shares.
2. Call `redeem(uint256 earnShares, address receiver, uint256 minAssets)`.
3. Wait for a successful receipt and refresh the share and deposit-token balances.

[Viem’s `earn.redeem`](https://viem.sh/tempo/actions/earn.redeem) provides the SDK
equivalent. Redemption is synchronous and depends on available pool liquidity.
A failed redemption leaves the shares in the wallet; it does not create a queued
withdrawal. Simulate before submitting and refresh the quote before retrying.

If you remove a wallet’s access through Ground’s API, deposits, share transfers,
and redemptions are blocked. Restore permission and wait for confirmed access
before the user can transfer or redeem again.

## If you want to configure a fee

Use your Ground API key to create an organization-specific wrapper over the
shared vault:

```http theme={"theme":{"light":"github-light","dark":"github-dark"}}
POST /v2/fee-wrappers
```

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "requestId": "a1b2c3d4-0000-4000-8000-000000000001",
  "gVaultId": "ground-tempo-prime-vault",
  "feeRecipientAddress": "0x3333333333333333333333333333333333333333",
  "performanceFeeBps": 2000,
  "managementFeeBps": 10
}
```

Use the catalogue’s `id` for `gVaultId` and a new UUID v4 for `requestId`; reuse
that UUID when retrying the same request. In this example, the recipient earns
20% of gains above the wrapper’s high-water mark and a 0.10% annual management
fee. Set either rate to zero to omit that fee. Both fees go to the same recipient.

1. Poll `GET /v2/fee-wrappers/{id}` until `status: ready`, then retain its
   `contractAddress`.
2. Authorize each user with `PUT /v2/fee-wrappers/{id}/allowlist/{address}` and
   poll the corresponding `GET` until `allowed: true`. Use this wrapper access
   flow instead of the vault authorization flow above.
3. Approve the deposit asset for the **wrapper**, then call
   `deposit(uint256 assets, address receiver, uint256 minWrapperShares)`.
4. Read `balanceOf(address)` on the wrapper. To exit, call
   `redeem(uint256 shares, address receiver, address owner, uint256 minAssets)`.

Use the wrapper’s ABI for these calls; Viem’s Tempo Earn helpers target the
underlying vault. Wrapper shares use 18 decimals and cannot be transferred.
Fees accrue as wrapper shares that the recipient can redeem for the deposit asset.

Update fees through `PATCH /v2/fee-wrappers/{id}/fees`. The initial performance
rate sets its permanent maximum. See [Manage fee wrappers](/docs/gtokens/manage-fee-wrappers)
for fee limits and recipient-update rules, and
[Manage fee-wrapper access](/docs/gtokens/manage-fee-wrapper-access) for access requests.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.