Earn with Trails - Polygon Developer Docs

Use the Trails Earn APIs to discover current markets and prepare deposits and withdrawals, then submit the returned transactions with an active OMS Wallet session. This guide uses a Polygon vault as a concrete example.

For a prebuilt React interface with market selection, deposits, and withdrawals, render the Trails Earn component. The widget can manage wallet connections itself or share an app-owned wallet through Trails adapters. For example, you can share an OMS Wallet session through the OMS Wallet connector and the Trails wagmi adapter. This guide instead uses OMS Wallet directly and calls the Earn APIs without the widget.

Prerequisites

An active OMS Wallet session from the TypeScript quickstart
A Trails API key
A balance of the selected market’s input asset and enough balance in an available fee token when the transaction is not sponsored

This guide submits mainnet transactions with real funds. Earn markets differ in provider, rate, fees, liquidity, and risk. Present the selected market’s current details before asking the user to confirm a deposit.

Install the Trails packages

pnpm add @polygonlabs/oms-wallet @0xtrails/api 0xtrails viem

Discover an Earn market

Do not hardcode a market ID. Fetch the current catalog and present the available markets for the user to select:

import { TrailsApi } from '@0xtrails/api'
import {
  getEarnBalances,
  getEarnMarkets,
} from '0xtrails/actions'
import {
  FeeOptionSelector,
  Networks,
  TransactionStatus,
} from '@polygonlabs/oms-wallet'
import {
  type Address,
  type Hex,
} from 'viem'

const trailsClient = new TrailsApi('YOUR_TRAILS_API_KEY')
const walletAddress = omsWallet.wallet.walletAddress as Address
const selectedNetwork = Networks.polygon

const markets = await getEarnMarkets(
  {
    chain: selectedNetwork.id,
    type: 'vault',
    limit: 50,
  },
  trailsClient,
)

const enterableMarkets = markets.items.filter(
  (candidate) =>
    candidate.status.enter && candidate.inputTokens.length > 0,
)

for (const candidate of enterableMarkets) {
  console.log({
    marketId: candidate.id,
    name: candidate.metadata.name,
    provider: candidate.providerId,
    inputAssets: candidate.inputTokens.map((token) => token.symbol),
    rate: candidate.rewardRate.total,
    tvlUsd: candidate.statistics?.tvlUsd,
    risk: candidate.risk?.ratings,
  })
}

// Use the market selected in your UI.
const selectedMarketId = 'MARKET_ID'
const market = enterableMarkets.find(
  (candidate) => candidate.id === selectedMarketId,
)

if (!market) {
  throw new Error('The selected market is not currently available.')
}

const inputToken = market.inputTokens[0]

if (!inputToken) {
  throw new Error('The selected market does not have an input asset.')
}

This example lists vaults and uses the selected market’s first supported input asset to keep the flow focused. Use type: 'lending' to list lending markets, or add search: 'USDC' to filter by asset. Refresh the catalog before preparing a deposit because market availability can change. See Earn markets and providers for other filters.

Prepare and submit a deposit

Pass a human-readable amount and the selected market’s input asset to yieldCreateEnterAction. Trails may return more than one unsigned transaction, such as an approval followed by the deposit. Submit every non-message transaction in order:

const deposit = await trailsClient.yieldCreateEnterAction({
  earnMarketId: market.id,
  userWalletAddress: walletAddress,
  args: {
    amount: '10',
    inputToken: inputToken.address ?? inputToken.symbol,
    inputTokenNetwork: inputToken.network,
    receiverAddress: walletAddress,
  },
})

for (const item of deposit.action.transactions) {
  if (item.isMessage) continue

  const unsigned =
    typeof item.unsignedTransaction === 'string'
      ? JSON.parse(item.unsignedTransaction)
      : item.unsignedTransaction

  if (!unsigned?.to || Number(unsigned.chainId) !== selectedNetwork.id) {
    throw new Error('Trails returned an unsupported deposit transaction.')
  }

  const tx = await omsWallet.wallet.sendTransaction({
    network: selectedNetwork,
    to: unsigned.to as Address,
    data: (unsigned.data ?? '0x') as Hex,
    value: unsigned.value == null ? 0n : BigInt(unsigned.value),
    selectFeeOption: FeeOptionSelector.firstAvailable,
  })

  if (tx.status !== TransactionStatus.Executed || !tx.txnHash) {
    throw new Error(`The deposit transaction ended with ${tx.status}.`)
  }

  console.log('Deposit transaction:', { txnId: tx.txnId, txnHash: tx.txnHash })
}

Each call to sendTransaction has its own OMS transaction lifecycle. Confirm a successful terminal status before submitting the next transaction in the sequence.

Read Earn positions

Earn balance reads do not require the active session and can query any wallet address. Request the wallet’s positions on the selected network and match each yieldId to the current market catalog:

const balances = await getEarnBalances(
  {
    queries: [
      {
        address: walletAddress,
        network: market.network,
      },
    ],
  },
  trailsClient,
)

for (const error of balances.errors) {
  console.error(`Could not read ${error.yieldId}: ${error.error}`)
}

function getPositiveEarnBalance(
  position: (typeof balances.items)[number],
) {
  if (
    position.outputTokenBalance &&
    BigInt(position.outputTokenBalance.amountRaw) > 0n
  ) {
    return position.outputTokenBalance
  }

  return position.balances.find((item) => BigInt(item.amountRaw) > 0n)
}

for (const position of balances.items) {
  const balance = getPositiveEarnBalance(position)

  if (!balance) continue

  const currentMarket = markets.items.find(
    (candidate) => candidate.id === position.yieldId,
  )

  console.log({
    marketId: position.yieldId,
    name: currentMarket?.metadata.name ?? position.yieldId,
    amount: balance.amount,
    symbol: balance.token.symbol,
    amountUsd: balance.amountUsd,
    rate: position.rewardRate?.total ?? currentMarket?.rewardRate.total,
  })
}

Treat the returned rate and USD value as current display data. Refresh the position after a deposit or withdrawal reaches a successful terminal status.

Withdraw a position

Use a positive balance from the previous response and verify that its current market permits exits. This example withdraws the full displayed position:

const position = balances.items.find(
  (item) => item.yieldId === market.id,
)
const balance = position
  ? getPositiveEarnBalance(position)
  : undefined

if (!position || !balance || !market.status.exit) {
  throw new Error('The selected Earn position is not withdrawable.')
}

const withdrawal = await trailsClient.yieldCreateExitAction({
  earnMarketId: position.yieldId,
  userWalletAddress: walletAddress,
  args: {
    amount: balance.amount,
    outputToken: balance.token.address ?? balance.token.symbol,
    outputTokenNetwork: balance.token.network,
  },
})

for (const item of withdrawal.action.transactions) {
  if (item.isMessage) continue

  const unsigned =
    typeof item.unsignedTransaction === 'string'
      ? JSON.parse(item.unsignedTransaction)
      : item.unsignedTransaction

  if (!unsigned?.to || Number(unsigned.chainId) !== selectedNetwork.id) {
    throw new Error('Trails returned an unsupported withdrawal transaction.')
  }

  const tx = await omsWallet.wallet.sendTransaction({
    network: selectedNetwork,
    to: unsigned.to as Address,
    data: (unsigned.data ?? '0x') as Hex,
    value: unsigned.value == null ? 0n : BigInt(unsigned.value),
    selectFeeOption: FeeOptionSelector.firstAvailable,
  })

  if (tx.status !== TransactionStatus.Executed || !tx.txnHash) {
    throw new Error(`The withdrawal transaction ended with ${tx.status}.`)
  }

  console.log('Withdrawal transaction:', { txnId: tx.txnId, txnHash: tx.txnHash })
}

Refresh the Earn balances after the final withdrawal transaction succeeds. Preserve each OMS txnId so you can resolve an uncertain transaction status before retrying.

Combine a swap and deposit

To swap into a market’s input asset and deposit it in one same-chain transaction, use Trails composable swap and lend or deposit actions with dynamic(). This action-based flow is separate from the routed intent lifecycle in the swap guide. See building composable actions for the action builders and the Trails actions example for a complete OMS Wallet implementation.

​Prerequisites

​Install the Trails packages

​Discover an Earn market

​Prepare and submit a deposit

​Read Earn positions

​Withdraw a position

​Combine a swap and deposit

Prerequisites

Install the Trails packages

Discover an Earn market

Prepare and submit a deposit

Read Earn positions

Withdraw a position

Combine a swap and deposit