Skip to main content
Earn lets a user deposit into a yield vault from any supported asset, then withdraw later. The swap widget ships Earn as a prebuilt screen, covered in offer vault deposits. This page covers the same capability through the headless core, for when you build the UI yourself. Use Earn for vaults supported by its integration. Find vaults with searchVaults or getVaultDetails; a returned vault does not guarantee that a deposit can be built. Pass vault: { vaultId, network } on buildRoute, and Trustware builds the deposit call. For a custom destination contract, or a deposit call you encode yourself, use a destination posthook instead. Who owns the vault doesn’t decide which one you use.
Requires @trustware/sdk 1.1.17 or later. Vaults and the positions they credit are on EVM chains, and withdrawing needs an EVM wallet.

Choose an integration

Earn isn’t separate settlement infrastructure. Trustware turns vault into a destination call, so an Earn deposit runs on providers that support destination calls and shares their constraints. Picking vaults in advance, as a preset or a fixed list in your UI, is a selection choice, not a separate API. A supported vault still uses vault, and a call you encode still uses hooks.postHook. Using hooks.postHook doesn’t add a contract to Earn, so Earn’s positions and withdrawals only cover vaults Earn supports.

Methods

Without the SDK, the same flow runs on the Earn vault endpoints and POST /route. VaultDepositRequest is exported from the package root. The other vault types are exported from @trustware/sdk/core, not the package root. See Earn types. The read methods throw on a failed request, including a 503 when vault data is temporarily unavailable. The error is an Error whose name is "HttpError", with a numeric status.

Find a vault

searchVaults returns one page of vaults that match your filters.
  • perPage takes 1 to 10 and defaults to 10. A larger value fails with 400.
  • To fetch the next page, pass nextPage as page. nextPage is absent on the last page.
  • Show each vault’s flags and warnings with it.
If you offer a fixed list of vaults, skip search and fetch each one with getVaultDetails. It takes the vault’s network name first, then its vaultId, which is the vault’s contract address.
See VaultSearchParams for every filter.

Deposit into a vault

Pass the vault as vault on buildRoute. Set the destination to the vault’s chain and asset, and set toAddress to the wallet that should hold the position.
Trustware turns the vault into a destination call that deposits the whole amount the route delivers. That uses amount patching, and how the amount is patched is provider dependent. If the deposit call fails, the delivered tokens go to toAddress when the resolving provider implements a fallback. Not every provider does, so this is not a guarantee. Not every vault can be deposited into through a route. When Trustware can’t build the deposit for a vault, buildRoute throws a RouteError with the reason. Treat it like any other failed build. vault and hooks are mutually exclusive, because Trustware builds the destination call itself. buildRoute throws before sending when both vault and hooks.postHook are set, and when vault.vaultId or vault.network is empty. To run the same checks in your own form validation, call assertValidVaultRequest from @trustware/sdk/core. From here, the deposit is an ordinary route. Show the estimate, then send it, submit the receipt, and poll status as in sign and send a route. For a Solana source, use review, then send.

Show positions

getVaultPositions lists every vault position a wallet holds, including vaults you don’t offer. Filter the result if you only show your own vaults.
Use lpToken.balanceUsd for a position’s USD value. asset.balanceUsd is the wallet’s total balance of the asset token, repeated on every position row. It is not the value of the position, and summing it across positions overcounts.
asset.positionValueInAsset is the position’s value in the asset’s base units, scaled by asset.decimals. A position’s apy is a single { base, reward, total } window. For the full vault, including every APY window, call getVaultDetails(position.network.name, position.vaultId). Positions are cached for up to a minute, so a new deposit can take a short time to appear.

Withdraw from a position

A withdrawal is not a route. It runs on the vault’s own chain, and the vault’s asset returns to the wallet that holds the position. There is no intentId, so don’t call submitReceipt or pollStatus.
  • all: true withdraws the whole position. To withdraw part of it, pass amount instead: the number of vault shares in base units, scaled by lpToken.decimals. Don’t scale it by asset.decimals, because a share isn’t always worth one unit of the asset. You can’t pass both.
  • assetAddress is required, even with all: true. Use position.asset.address.
  • address owns the shares and receives the asset. Pass the connected wallet’s address, because sendVaultRedeemTx signs with the connected wallet.
  • Send the returned actions in order. sendVaultRedeemTx switches the wallet to the action’s chain if needed, then sends the transaction. It resolves with the hash once the wallet submits, not when the transaction confirms.
  • The SDK doesn’t wait between actions. Wait for each transaction to confirm before you send the next, and stop if one fails.
The prebuilt widget only offers full withdrawals. That limit belongs to the widget, not to getVaultRedeemActions. To move the withdrawn asset to another token, chain, or vault, build a new route with it as the source once the withdrawal confirms. The user signs that route as a separate transaction.

Swap mode

The prebuilt Earn screen, configured with features.vaultDeposits.

Deposit into vault destinations

Encode your own destination call with hooks.postHook.

Earn types

VaultSummary, Position, VaultRedeemParams, and the other vault types.

Earn vault endpoints

Vault search, details, positions, and withdrawals over REST, plus the vault field on POST /route.