Skip to main content
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, 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 endpoint:
Use https://production.groundtech.co for mainnet. Create your API key in the Ground Developer Portal 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: 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 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 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 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 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. 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 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

Tempo fee-wrapper provisioning is pending API rollout. Once enabled, use your Ground API key to create an organization-specific wrapper over the shared vault:
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 for fee limits and recipient-update rules, and Manage fee-wrapper access for access requests.